diff --git a/README.md b/README.md index 759764fe..8b3124ee 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ conda env create -f environment.yml # first time: create the agentlab environm ./scripts/dev.sh # after that: one command starts the frontend and backend ``` -Open http://localhost:5273 . You can try everything without an API key: the built-in Mock provider runs the whole orchestration path end to end; to connect a real model, see [Model access](docs/en/configuration.md#model-access). The 11 built-in templates run as they are. +Open http://localhost:5273 . You can try everything without an API key: the built-in Mock provider runs the whole orchestration path end to end; to connect a real model, see [Model access](docs/en/configuration.md#model-access). The 12 built-in templates run as they are. **Login is off by default**: anyone on the same network who can open the page can use every feature. Turn on login before multiple people use it; see [Login modes](docs/en/identity-and-security.md#login-modes). For more startup options, see [Development](docs/en/development.md#start). @@ -88,15 +88,15 @@ See [Deployment](docs/en/deployment.md) and [deploy/README.md](deploy/README.md) | Document | What it covers | |---|---| | **Using and building** | | -| [Ask Data and Copilot](docs/en/ask-data.md) | What happens after you ask, output review, record retention, how Copilot builds graphs and looks things up | +| [Ask Data and Copilot](docs/en/ask-data.md) | What happens after you ask, cross-source ontology penetration and anomaly escalation, output review, record retention, how Copilot builds graphs and looks things up | | [Workflows](docs/en/workflows.md) | The canvas, node types, passing data, human nodes and rejection, agent guardrails, subworkflows, publishing and gates, runs and resuming | | [Evidence and Issuance](docs/en/evidence.md) | Caliber cards, issuance contracts and tiers, citation markers, claim sentences, no data in the queried range, sealing and verification, report exports and verifiable reports, the review suite | -| [Analysis](docs/en/analysis.md) | The five analyses and their criteria, when an analysis can't be done, analysis tools for agents and analysis cards, how to cite, the analysis claim check, the analysis scope, settings and limits | +| [Analysis](docs/en/analysis.md) | Single-source analyses, cross-source reconciliation and co-movement, source health probes, analysis tools and cards, citations, analysis claim checks, analysis scope, settings and limits | | [Data Sources and Spreadsheet Import](docs/en/data-sources.md) | Connecting databases, read-only guarantees, uploading spreadsheets and recipes, accumulating by period, cross-database merges, masked columns | -| [Data Catalog](docs/en/data-catalog.md) | What the catalog records, drafting and review, export and import, data profiling, SQL checks, introspection scope for large databases, schema and value changes | +| [Data Catalog](docs/en/data-catalog.md) | What the catalog records, drafting and review, export and import, data profiling, SQL checks, introspection scope for large databases, schema and value changes, canonical entity bridges | | [Tools, MCP, and the Capability Registry](docs/en/tools.md) | Kinds of tools, approval levels, capability governance, limits on write capabilities, registered endpoints, network rules | | [Apps](docs/en/apps.md) | Creating apps, views and stamps, processes and tasks, writing to external systems, form submissions, personal apps, external integration | -| [Evaluation and the Caliber Ledger](docs/en/evaluation-and-ledger.md) | Test suites and evaluation results, caliber labels per number, issuance by caliber, reconciliation, distilling, recall | +| [Evaluation and the Caliber Ledger](docs/en/evaluation-and-ledger.md) | Test suites and ontology penetration presets, evaluation results, caliber labels per number, issuance by caliber, reconciliation, distilling, recall, metric ontology topology | | [Schedules, Event Triggers, and Notifications](docs/en/schedules.md) | Schedules, event triggers, notification channels and email, subscribable events | | **Deployment and operations** | | | [Deployment](docs/en/deployment.md) | `prod.sh`, the Docker offline bundle, the data directory, backups, upgrades | @@ -120,7 +120,7 @@ cd frontend && npx tsc -b node scripts/check-all.mjs # frontend checks; start ./scripts/dev.sh first ``` -For tests on PostgreSQL, the 43 frontend checks, and the documentation checks, see [Development](docs/en/development.md). +For tests on PostgreSQL, the 45 frontend checks, and the documentation checks, see [Development](docs/en/development.md). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 1d53df40..598ddb6c 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -72,7 +72,7 @@ conda env create -f environment.yml # 首次:创建 agentlab 环境并安装 ./scripts/dev.sh # 之后:一条命令启动前后端 ``` -打开 http://localhost:5273 。不配 API Key 也能完整体验:内置的 Mock 会把编排链路完整走一遍;接入真实模型见[模型接入](docs/zh-CN/configuration.md#模型接入)。内置 11 个模板可以直接运行。 +打开 http://localhost:5273 。不配 API Key 也能完整体验:内置的 Mock 会把编排链路完整走一遍;接入真实模型见[模型接入](docs/zh-CN/configuration.md#模型接入)。内置 12 个模板可以直接运行。 **默认不开登录**:同一网络里打得开页面的人都能用全部功能。多人使用前先开登录,见[登录方式](docs/zh-CN/identity-and-security.md#登录方式)。更多启动选项见[开发](docs/zh-CN/development.md#启动)。 @@ -88,15 +88,15 @@ conda env create -f environment.yml # 首次:创建 agentlab 环境并安装 | 文档 | 讲什么 | |---|---| | **使用与搭建** | | -| [问数据与助手](docs/zh-CN/ask-data.md) | 提问之后发生什么、产出复核、记录保留,助手怎么生成图、怎么按需查看 | +| [问数据与助手](docs/zh-CN/ask-data.md) | 提问之后发生什么、跨源本体穿透与异常升级、产出复核、记录保留,助手怎么生成图、怎么按需查看 | | [工作流](docs/zh-CN/workflows.md) | 画布、节点类型、传数据、人工节点与驳回、agent 护栏、子工作流、发布与门禁、运行与断点续跑 | | [证据与出具](docs/zh-CN/evidence.md) | 口径卡、出具契约与三档、引用标记、结论句、查询区间里没有数据、封存与核对、报告导出与可验证报告、复核套件 | -| [分析能力](docs/zh-CN/analysis.md) | 五种分析与判定标准、算不了的时候、Agent 的分析工具与分析卡、引用写法、分析说法核对、分析范围、设置与限制 | +| [分析能力](docs/zh-CN/analysis.md) | 单源分析与跨源对账/伴随异动、数据源健康探针、Agent 分析工具与分析卡、引用写法、分析说法核对、分析范围、设置与限制 | | [数据源与表格导入](docs/zh-CN/data-sources.md) | 接入数据库、只读保证、上传表格与取数配方、按期累积、跨库合并、遮罩列 | -| [数据目录](docs/zh-CN/data-catalog.md) | 目录记什么、起草与审阅、导出导入、数据剖析、SQL 检查、大库探查范围、结构与取值变化 | +| [数据目录](docs/zh-CN/data-catalog.md) | 目录记什么、起草与审阅、导出导入、数据剖析、SQL 检查、大库探查范围、结构与取值变化、标准业务实体桥 | | [工具、MCP 与能力登记](docs/zh-CN/tools.md) | 工具种类、审批档位、能力治理、写入能力的限制、登记端点、网络规则 | | [应用](docs/zh-CN/apps.md) | 生成应用、视图与印章、流程与待办、写外部系统、填报登记、个人应用、对外集成 | -| [回归评测与口径账本](docs/zh-CN/evaluation-and-ledger.md) | 题集与评测结果、逐个数标口径、按口径出具、对账、沉淀、召回 | +| [回归评测与口径账本](docs/zh-CN/evaluation-and-ledger.md) | 题集与本体穿透对照、评测结果、逐个数标口径、按口径出具、对账、沉淀、召回、指标本体拓扑 | | [定时任务、事件触发与通知](docs/zh-CN/schedules.md) | 定时任务、事件触发、通知渠道与邮件、可订阅的事件 | | **部署运维** | | | [部署](docs/zh-CN/deployment.md) | `prod.sh`、Docker 离线包、数据目录、备份、升级 | @@ -120,7 +120,7 @@ cd frontend && npx tsc -b node scripts/check-all.mjs # 前端检查,先起 ./scripts/dev.sh ``` -PostgreSQL 上的测试、43 项前端检查和文档检查见[开发](docs/zh-CN/development.md)。 +PostgreSQL 上的测试、45 项前端检查和文档检查见[开发](docs/zh-CN/development.md)。 ## License diff --git a/backend/app/api/chat_turns.py b/backend/app/api/chat_turns.py index 22b33176..080d0653 100644 --- a/backend/app/api/chat_turns.py +++ b/backend/app/api/chat_turns.py @@ -15,7 +15,7 @@ conversations.turn_access / ensure_conversation_access);访问密钥调不 """ from __future__ import annotations -from typing import Any +from typing import Any, Literal from fastapi import APIRouter, Depends, Header, HTTPException, Query from fastapi.responses import StreamingResponse @@ -40,6 +40,8 @@ class TurnStartIn(BaseModel): mode: str | None = None #: 放宽到几步(mode=max_steps) max_steps: int | None = Field(default=None, ge=1, le=10_000) + #: 问数模式:fast 快速直查(毫秒级语义预命中 + 确定性直查图) | deep 深度分析(助手规划建工作流 + 报告 + 复核) + depth: Literal["fast", "deep"] | None = None def _refused(e: Any) -> HTTPException: @@ -64,7 +66,7 @@ async def start_turn(payload: TurnStartIn, session: AsyncSession = Depends(get_s try: turn_id = await chat_job.start(session, conversation=conversation, question=payload.question, datasource_ids=payload.datasource_ids, actor=actor_of(x_actor), mode=payload.mode, - retry_of=retry_of, max_steps=payload.max_steps) + retry_of=retry_of, max_steps=payload.max_steps, depth=payload.depth) except chat_job.TurnRefused as e: raise _refused(e) from e from app.db.base import SessionLocal diff --git a/backend/app/api/copilot.py b/backend/app/api/copilot.py index 63b2b5ea..21c8b314 100644 --- a/backend/app/api/copilot.py +++ b/backend/app/api/copilot.py @@ -78,7 +78,8 @@ def _scope_note(rows: list[Any], scoped: bool) -> str: "db_schema__ 工具;前几轮用过别的库,这一轮也不要沿用") -def _tool_catalog(rows: list[Any], *, builtins: frozenset[str] | None = None, analysis_tools: bool = True) -> str: +def _tool_catalog(rows: list[Any], *, builtins: frozenset[str] | None = None, analysis_tools: bool = True, + ontology_tools: bool = True) -> str: """给助手看的工具清单。 all_specs() 只有静态注册的内置工具,数据源工具是运行时按库动态生成的 @@ -88,14 +89,18 @@ def _tool_catalog(rows: list[Any], *, builtins: frozenset[str] | None = None, an 不列表名(look 文档 D3):以前每个库列前 12 个表名,和这一轮要做什么无关,闲聊也带着;表数写一句,字段要用时 look。 builtins 给了的话内置工具只列这几个:使用者的问数据(_CHAT_USER_PROMPT)只能用只读的那几个,列出来用不了的工具, - 模型照样会绑。analysis_tools 为假(评测「关掉分析工具」那一臂,answer_ops)时不列五个分析工具。 + 模型照样会绑。analysis_tools 为假(评测「关掉分析工具」那一臂,answer_ops)时不列分析工具;ontology_tools 为假 + (评测「关掉本体穿透」那一臂)时不列 ontology_neighbors、source_health。 """ from app.tools.analysis import ANALYSIS_TOOLS + from app.tools.ontology import ONTOLOGY_TOOLS lines = [ f"- {name}({spec.category}):{spec.description}" for name, spec in sorted(all_specs().items()) - if (builtins is None or name in builtins) and (analysis_tools or name not in ANALYSIS_TOOLS) + if (builtins is None or name in builtins) + and (analysis_tools or name not in ANALYSIS_TOOLS) + and (ontology_tools or name not in ONTOLOGY_TOOLS) ] from app.data import introspect as _introspect @@ -117,7 +122,7 @@ def _tool_catalog(rows: list[Any], *, builtins: frozenset[str] | None = None, an async def _look_service(session: AsyncSession, payload: GenerateIn, sources: list[Any], *, graph: dict[str, Any] | None, kinds: tuple[str, ...] = ("table", "capability"), catalog_view: Any = None, caliber: str = copilot_context.CALIBER_LOOK, - actor: Any = None) -> Any: + actor: Any = None, ontology: bool = True) -> Any: """这一轮的查看服务(copilot_context.look_service)。挑选模型用同一个助手模型,第一次要挑时才拿。catalog_view:表详情 里给哪一份数据目录(data/catalog_view.py),不给是当前目录。 @@ -128,7 +133,7 @@ async def _look_service(session: AsyncSession, payload: GenerateIn, sources: lis return await copilot_context.look_service(sources, spec=spec, graph=graph, kinds=kinds, answer=payload.intent == "answer", catalog_view=catalog_view, trail={"conversation_id": getattr(payload, "conversation_id", None)}, - session=session, actor=actor, caliber=caliber) + session=session, actor=actor, caliber=caliber, ontology=ontology) NODE_REFERENCE = """\ @@ -148,11 +153,15 @@ NODE_REFERENCE = """\ 单引号(那是字符串)。只给最外层 SELECT 的结果列起别名,WHERE、JOIN、GROUP BY 里照旧写原列名;Oracle 旧版本 的标识符最长 30 字节,别名不超过 10 个字 **问题问的是为什么、怎么变了、哪里拖累、谁贡献最大、是否异常、波动、趋势、是不是真的更高这类分析问题时**,查库的 agent - 除了 db_query__ / db_schema__ 再绑上五个分析工具(analysis_comparable、analysis_baseline、analysis_trend、 - analysis_decompose、analysis_differ):变化从哪来、算不算异常、是不是持续在变、差异站不站得住由平台按固定的方法和阈值算, - 判定语由系统写好,报告引用它;agent 只决定算什么(比哪两期、拆哪个维度、往哪一段下钻)。绑了任一个,平台就把分析方法 - 注入 agent 的 system,prompt 里不用再教方法,也不要写阈值。分析工具只分析这个 agent 自己查过的结果,所以只绑给同时绑了 - db_query__ 的 agent;不能放进 tool 节点(模板里每次都要做的固定分析用 analysis 分析卡) + 除了 db_query__ / db_schema__ 再绑上分析工具(analysis_comparable、analysis_baseline、analysis_trend、 + analysis_decompose、analysis_differ、analysis_reconcile、analysis_cochange),涉及已发布口径异常或跨源排查时一并绑上 + ontology_neighbors、source_health 和 caliber_query:变化从哪来、算不算异常、是不是持续在变、差异站不站得住、跨源对账是否 + 背离、上游指标是否伴随异动由平台按固定的方法和阈值算,判定语由系统写好,报告引用它;agent 只决定算什么(先验数据源健康与 + 跨源对账、发现断更或缺口即早停,通过后再拆维度或沿本体穿透)。跨源穿透以 caliber_query(在 inputs 中传对侧编码或标准实体键自动对齐实体编码) + 为主路径;搭建者在 look 看到已确认的跨源标准实体桥时,可在对齐粒度后额外绑 1 跳关联源的 db_query__<关联源> 核查主数据或明细。 + 绑了任一个分析或本体工具,平台就把分析方法(含三段式穿透与健康检查规则)注入 agent 的 system,prompt 里不用再教方法,也不要写阈值。分析工具只分析这个 + agent 自己查过的结果,所以只绑给同时绑了 db_query__ 或 caliber_query 的 agent;不能放进 tool 节点(模板里每次都要做的 + 固定分析用 analysis 分析卡) **默认不要写 max_steps、budget_tokens、budget_usd**。平台用的是护栏而不是固定步数: 步数只是很高的兜底(跟随设置,默认 100),重复调用、连续几步没有新信息、预算用完、 上下文快满时,它会按查到的部分收尾。写死一个小数字(见过 8)会让它查完表结构就没额度回答了。 @@ -235,7 +244,7 @@ NODE_REFERENCE = """\ 这周的变化在不在常规波动范围内、主要来自哪个地区)。问数据里要看了数才知道拆哪个维度的不用它,给查库的 agent 绑分析工具。 config: {items:[{id, op, mode, from, params, hypothesis}], overrides, assign_to} · op:decompose(变化拆解,mode 选 additive 可加 / ratio 比率 / factor 乘积)、baseline(波动基线)、trend(趋势)、 - differ(差异检验,mode 选 rate / mean / rows)、comparable(可比性检查);hypothesis 一句话写这一项在验证什么 + differ(差异检验,mode 选 rate / mean / rows)、comparable(可比性检查)、reconcile(跨源对账)、cochange(伴随异动);hypothesis 一句话写这一项在验证什么 · from 是要分析的上游查询节点 id:只能是调用 db_query__ 的 tool 节点或 merge 节点,而且连在分析卡之前;agent 不能当 输入(它可能查了好几次)。基期、本期是两份查询时不写 from,在 params 里写 base_query、target_query 两个节点 id · params 和同名分析工具的参数一样(period、measure、by、base、target、headline……,不写 query),可以用 {{ input.x }} @@ -278,10 +287,11 @@ NODE_REFERENCE = """\ 「根据 [[see:…]]」这样把它当成句子成分的示例,模型照着写会留下「以 为依据」这样的断句 - 分析结论:[[a:A1]] 渲染成 A1 的判定语(系统按判定写好的一句,连同里面的数);[[a:A1.top_share|pct]] 是它的一个具名的数 (换算后缀同 [[m:]]);[[v:A1.r0.share]]、[[table:A1 cols=地区,delta,share rows=0-4]] 取它的结果表;句末的 [[see:A1]] - 把它当这句的依据。「主要来自」「集中在」「拖累」「异常」「大幅」「持续上升」「趋势」「显著高于」这类判断只能照分析结论的 - 判定写、挂它当依据(最好直接引用判定语),没有对应的分析结论就只陈述数字和变化;拆解只说明变化来自哪里、说明不了为什么, - 写原因要有知识库原话或运行输入作依据,否则写成待核实的推测。这些规矩系统会告诉写作者,instructions 里写「按分析结论写、 - 判断引用判定语」就够了,不要替它把判断写好 + 把它当这句的依据;数据源健康探查(source_health)编成 H1、H2…,用 [[h:H1]] 渲染健康判定语、句末挂 [[see:H1]] 作数据断更或 + 缺口的依据。「主要来自」「集中在」「拖累」「异常」「大幅」「持续上升」「趋势」「显著高于」「伴随同步异动」这类判断只能照分析或 + 健康结论的判定写、挂它当依据(最好直接引用判定语),没有对应的分析结论就只陈述数字和变化;拆解与伴随异动(cochange)只说明 + 变化来自哪里或统计上同步异动、说明不了为什么,写「由于…导致」要有知识库原话或运行输入作依据,否则写伴随异动或待核实的推测。 + 这些规矩系统会告诉写作者,instructions 里写「按分析结论写、判断引用判定语」就够了,不要替它把判断写好 - 涉及码值(状态、类型这类用数字编码的取值)时,instructions 里让模型写它的含义(「作废记录」),不要写码值本身: 码值是没有出处的数字,会被数字核对打回重写 metrics_from 不写就取所有上游口径卡;on_violation 不写时探索运行是 flag(标出来、照常产出),正式运行是 fail; @@ -427,17 +437,27 @@ _ANALYSIS_PROMPT_CUTS = ( ) -def node_reference(*, analysis_tools: bool = True) -> str: +_ONTOLOGY_PROMPT_EDITS = ( + (",涉及已发布口径异常或跨源排查时一并绑上\n ontology_neighbors、source_health 和 caliber_query", ""), + ("绑了任一个分析或本体工具,平台就把分析方法(含三段式穿透与健康检查规则)注入 agent 的 system,", "绑了任一个分析工具,平台就把分析方法注入 agent 的 system,"), + (";数据源健康探查(source_health)编成 H1、H2…,用 [[h:H1]] 渲染健康判定语、句末挂 [[see:H1]] 作数据断更或\n 缺口的依据", ""), +) + + +def node_reference(*, analysis_tools: bool = True, ontology_tools: bool = True) -> str: """给助手的节点手册。analysis_tools 为假时去掉讲分析能力的那几段(_ANALYSIS_PROMPT_SPANS、_ANALYSIS_PROMPT_CUTS), - 改写顺带提到它的几句(_ANALYSIS_PROMPT_EDITS):手册里不再出现分析卡、分析工具和分析相关的配置键。""" - if analysis_tools: - return NODE_REFERENCE + 改写顺带提到它的几句(_ANALYSIS_PROMPT_EDITS):手册里不再出现分析卡、分析工具和分析相关的配置键;ontology_tools 为假时 + 去掉提到本体穿透与数据源健康工具的几处。""" text = NODE_REFERENCE - for start, end in (*_ANALYSIS_PROMPT_SPANS, *_ANALYSIS_PROMPT_CUTS): - i = text.index(start) - text = text[:i] + text[text.index(end, i):] - for old, new in _ANALYSIS_PROMPT_EDITS: - text = text.replace(old, new, 1) + if not analysis_tools: + for start, end in (*_ANALYSIS_PROMPT_SPANS, *_ANALYSIS_PROMPT_CUTS): + i = text.index(start) + text = text[:i] + text[text.index(end, i):] + for old, new in _ANALYSIS_PROMPT_EDITS: + text = text.replace(old, new, 1) + if not ontology_tools: + for old, new in _ONTOLOGY_PROMPT_EDITS: + text = text.replace(old, new, 1) return text @@ -473,17 +493,29 @@ def _question_of(payload: GenerateIn) -> str | None: #: 问数据的包装里「分析类问题」那一条形状(00-总方案 §3.7):问原因、来源、异常、趋势、差异的,判定由平台的分析工具算、系统写 #: 判定语,报告引用它。问题意图另由自查按 app/analysis/intent 的词表再核一遍:分析类问题而查库的 agent 没绑分析工具时交回改一轮 ANALYSIS_SHAPE_PROMPT = ( - "- 问的是为什么、怎么变了、哪里拖累、谁贡献最大、是否异常、正常吗、波动、趋势、是不是真的更高这类分析问题时,搭 " - "input → agent → report → output:agent 绑 db_query__、db_schema__ 和五个分析工具(analysis_comparable、" - "analysis_baseline、analysis_trend、analysis_decompose、analysis_differ),prompt 里写清要回答的问题、比哪两期" - "(问题没说就比上一个整期),不用教分析方法(平台会注入)、不写阈值;report 的 instructions 写「回答:{{ input.question }}。" - "按分析结论写,判断直接引用判定语;没有分析结论的判断不下,原因没有依据的写成待核实的推测」(可以附上 " - "{{ nodes.agent的id.text }} 当分析思路):数引用 agent 查过的单元格,判定引用它做过的分析结论。analysis_claims " - "用默认,不要关\n" + "- 问的是为什么、怎么变了、哪里拖累、谁贡献最大、是否异常、正常吗、波动、趋势、是不是真的更高、指标为什么越界或两套账对不上这类分析问题时,搭 " + "input → agent → report → output:agent 绑 db_query__、db_schema__、分析工具(analysis_comparable、" + "analysis_baseline、analysis_trend、analysis_decompose、analysis_differ、analysis_reconcile、analysis_cochange)以及 " + "ontology_neighbors、source_health、caliber_query(跨源穿透优先走 caliber_query 在 inputs 中自动对齐实体编码,搭建者有已确认跨源标准实体桥时可辅以 1 跳关联源 db_query__)," + "prompt 里写清要回答的问题、比哪两期(问题没说就比上一个整期),不用教分析方法(平台会注入三段式穿透与健康检查规则)、不写阈值;" + "report 的 instructions 写「回答:{{ input.question }}。按分析结论写(含数据源健康结论),判断直接引用判定语([[a:]] / [[h:]]);" + "没有分析结论的判断不下,伴随异动只写统计共变、原因没有依据的写成待核实的推测」(可以附上 {{ nodes.agent的id.text }} 当分析思路):" + "数引用 agent 查过的单元格,判定引用它做过的分析或源健康结论。analysis_claims 用默认,不要关\n" ) -def _user_message(payload: GenerateIn, *, patch: bool, analysis_tools: bool = True) -> str: +ANALYSIS_SHAPE_NO_ONTOLOGY_PROMPT = ( + "- 问的是为什么、怎么变了、哪里拖累、谁贡献最大、是否异常、正常吗、波动、趋势、是不是真的更高、指标为什么越界或两套账对不上这类分析问题时,搭 " + "input → agent → report → output:agent 绑 db_query__、db_schema__、分析工具(analysis_comparable、" + "analysis_baseline、analysis_trend、analysis_decompose、analysis_differ、analysis_reconcile、analysis_cochange)," + "prompt 里写清要回答的问题、比哪两期(问题没说就比上一个整期),不用教分析方法、不写阈值;" + "report 的 instructions 写「回答:{{ input.question }}。按分析结论写,判断直接引用判定语([[a:]]);" + "没有分析结论的判断不下,伴随异动只写统计共变、原因没有依据的写成待核实的推测」(可以附上 {{ nodes.agent的id.text }} 当分析思路):" + "数引用 agent 查过的单元格,判定引用它做过的分析结论。analysis_claims 用默认,不要关\n" +) + + +def _user_message(payload: GenerateIn, *, patch: bool, analysis_tools: bool = True, ontology_tools: bool = True) -> str: """把用户说的话包成给模型的请求。analysis_tools 为假(评测「关掉分析工具」那一臂)时不给分析类问题那一条形状。 两个入口的语义完全不同,包法必须跟着变: @@ -511,17 +543,18 @@ def _user_message(payload: GenerateIn, *, patch: bool, analysis_tools: bool = Tr # 而模板取不到值不报错,于是模型一本正经地基于空内容编一段回答 "- 问题已经由系统注入成 `{{ input.question }}`,要用就写这一个。" "入口节点**不要声明任何字段**,也不会有人再填一次表单\n" - "- 涉及数据的问题必须用 db_query__* / db_schema__* 去真查," + "- 涉及数据的问题先查已发布口径;已匹配且参数齐全时用 use_caliber 或已授权的 caliber_query 真查," + "不要重复发现表结构。没有适用口径、需要探索时才用 db_query__* / db_schema__*," "不要只对问题本身做文字加工(改写、摘要、分类都不是回答)\n" "- 出口节点给出的应当是这个问题的答案本身\n" # 二期起报告能直接引用 agent 查过的单元格:答案里的每个数都点得开出处,不必为问数硬塞一张口径卡。 # 只问表结构、清单的没有数要核对,多一次写作调用只是多等十几秒 - "- 答案里有数字时,搭 input → agent → report → output:agent 绑 db_query__ 去查,report 的 instructions 写" + "- 没有适用的已发布口径、需要探索且答案里有数字时,搭 input → agent → report → output:agent 绑 db_query__ 去查,report 的 instructions 写" "「回答:{{ input.question }}」(可以附上 {{ nodes.agent的id.text }} 当分析思路),数用 [[v:Q1.r0.列名]] " "直接引用 agent 查过的单元格,不必经过口径卡;要比率、增幅再在 agent 和 report 之间加口径卡,agent 配 " "output_schema + cite_fields,口径卡读 vars..字段。出口字段写 {{ nodes.report的id.text }}\n" - # 分析类问题那一条形状(ANALYSIS_SHAPE_PROMPT):评测「关掉分析工具」那一臂不给 - + (ANALYSIS_SHAPE_PROMPT if analysis_tools else "") + # 分析类问题那一条形状(ANALYSIS_SHAPE_PROMPT):评测「关掉分析工具」那一臂不给;「关掉本体穿透」那一臂去掉本体工具指引 + + ((ANALYSIS_SHAPE_PROMPT if ontology_tools else ANALYSIS_SHAPE_NO_ONTOLOGY_PROMPT) if analysis_tools else "") + "- 只问表结构、清单(有哪些表、有哪些字段、列出名单)的,不加 report,agent → output 就行\n" # 三期起报告会核对写出来的表名、字段名:instructions 里让它「列出用到的表」时,编出来的名字会被标出来 "- report 提到表名、字段名时写 [[t:表名]] / [[c:表名.字段名]](英文名也可以放进反引号,中文名不行:" @@ -940,18 +973,24 @@ GRAPH_SCHEMA: dict[str, Any] = { def _graph_system(sources: list[Any], scope: set[str] | None, datasources: str, looks: Any, *, - chat_user: bool = False, analysis_tools: bool = True) -> str: + chat_user: bool = False, analysis_tools: bool = True, ontology_tools: bool = True) -> str: """画布、问数据(流式和非流式)共用的 system:节点手册、工具清单、数据源概览、结构要求、输出协议、查看的用法。 这一份一直用到自查修正结束(接着写、修正轮都不换),模型前后看到的是同一套说法。 chat_user:开登录后 user 角色的问数据(D-c)。内置工具只列只读的那几个,结构要求后面再加一段使用者的约束。 - analysis_tools 为假(评测「关掉分析工具」那一臂):节点手册去掉只讲分析能力的几段,工具清单不列分析工具。""" + analysis_tools 为假(评测「关掉分析工具」那一臂):节点手册去掉只讲分析能力的几段,工具清单不列分析工具。 + ontology_tools 为假(评测「关掉本体穿透」那一臂):工具清单与手册去掉本体穿透工具。""" from app.auth.chat_policy import CHAT_BUILTIN_TOOLS - catalog = _tool_catalog(sources, builtins=CHAT_BUILTIN_TOOLS if chat_user else None, analysis_tools=analysis_tools) + catalog = _tool_catalog(sources, builtins=CHAT_BUILTIN_TOOLS if chat_user else None, + analysis_tools=analysis_tools, ontology_tools=ontology_tools) + user_prompt = _CHAT_USER_PROMPT if ontology_tools else _CHAT_USER_PROMPT.replace( + ";指标异常或要跨系统排查关联指标时,给 agent 绑上 ontology_neighbors、source_health 和 caliber_query(跨源对齐切片写在 inputs 里),只在已授权口径范围内穿透排查", + "", + ) return ( "你是一个 agent 工作流编排专家。根据用户需求,以操作流的方式逐步搭出一张可执行的工作流图。\n\n" - f"{node_reference(analysis_tools=analysis_tools)}\n\n可用工具:\n{catalog}" + f"{node_reference(analysis_tools=analysis_tools, ontology_tools=ontology_tools)}\n\n可用工具:\n{catalog}" f"{datasources}{_scope_note(sources, scope is not None)}\n\n" "结构要求:\n" "1. 必须有且只有一个 input 节点和至少一个 output 节点\n" @@ -959,7 +998,7 @@ def _graph_system(sources: list[Any], scope: set[str] | None, datasources: str, "3. 用 assign_to 传结果,下游 {{ vars.变量名 }} 引用\n" "4. 只能用上面列出的工具名\n" "5. 能用 3 个节点解决就别堆 8 个" - f"{_CHAT_USER_PROMPT if chat_user else ''}\n\n" + f"{user_prompt if chat_user else ''}\n\n" f"{_STREAM_PROTOCOL}" # 问数据里能选用已发布口径时(next-round 02 做法 4):协议多一段 use_caliber,「什么时候该看」换成问数据那一份 + (f"\n{copilot_context.USE_CALIBER_PROMPT}" if copilot_context.composing(looks) else "") @@ -985,8 +1024,9 @@ _CHAT_USER_PROMPT = ( "(tool 写 db_query__<数据源>,args.sql 写好 SQL)或 agent(tools 里绑定这两种数据源工具)。不要用 http_request、" "records_append 这类写入或连外部的工具,工具名不要用 {{ }} 拼\n" "3. 上面工具清单里有 caliber_query(口径查询):用户问的数只要在已发布口径里对得上,就照 look 交回的「取数写法」调它" - "取数(在 agent 的 prompt 里写清要调它、参数照抄),交回的指标值写进报告。**不要**自己拿 db_query__ 拼一份差不多的 SQL," - "口径的 SQL 你也看不到、不要照着抄;没有对得上的口径时才自己查表\n" + "取数(在 agent 的 prompt 里写清要调它、参数照抄),交回的指标值写进报告;指标异常或要跨系统排查关联指标时,给 agent 绑上 " + "ontology_neighbors、source_health 和 caliber_query(跨源对齐切片写在 inputs 里),只在已授权口径范围内穿透排查。" + "**不要**自己拿 db_query__ 拼一份差不多的 SQL 或直查未授权关联库的物理表,口径的 SQL 你也看不到、不要照着抄;没有对得上的口径时才自己查表\n" "4. 查询一律只读,不要写改数据的 SQL\n" "5. 任何节点、图级 defaults、tool 节点的 args 里都不要写 memory_scope、collection:记忆范围和知识库由平台定" ) @@ -1081,7 +1121,38 @@ def _analysis_off_issues(nodes: dict[str, dict[str, Any]], subgraphs: set[str] | return out -def _graph_request(payload: GenerateIn, *, analysis_tools: bool = True) -> str: +ONTOLOGY_TOOLS_OFF = "ontology_tools_off" + + +def _ontology_off_issues(nodes: dict[str, dict[str, Any]]) -> list[dict[str, Any]]: + """评测「关掉本体穿透」那一臂:图里绑定了 ontology_neighbors 或 source_health 的挡回模型去掉。""" + from app.tools.ontology import ONTOLOGY_TOOLS + + out: list[dict[str, Any]] = [] + for nid, node in nodes.items(): + cfg = ((node or {}).get("data") or {}).get("config") or {} + ntype = (node or {}).get("type") + title = str(((node or {}).get("data") or {}).get("label") or "").strip() or nid + if ntype == NodeType.TOOL: + names = [cfg.get("tool")] + elif ntype == NodeType.AGENT: + names = list(cfg.get("tools") or []) + elif ntype == NodeType.SUPERVISOR: + names = [t for m in cfg.get("agents") or [] if isinstance(m, dict) for t in m.get("tools") or []] + else: + continue + bound = list(dict.fromkeys(n.strip() for n in names if isinstance(n, str) and n.strip() in ONTOLOGY_TOOLS)) + if not bound: + continue + field = "tool" if ntype == NodeType.TOOL else "agents" if ntype == NodeType.SUPERVISOR else "tools" + out.append({"level": "error", "node_id": nid, "edge_id": None, "field": field, "code": ONTOLOGY_TOOLS_OFF, + "message": f"绑定的工具不存在:「{title}」绑定的 {'、'.join(bound)}。这一轮没有本体穿透工具可用,请在节点中去掉它们", + "for_model": f"「{nid}」绑定的 {'、'.join(bound)} 不在这一轮的工具清单里:从它的工具里去掉这几个,只用上面" + "列出的工具"}) + return out + + +def _graph_request(payload: GenerateIn, *, analysis_tools: bool = True, ontology_tools: bool = True) -> str: """这一轮的请求:改现有图时附上原图、只要改动操作;新建时按入口包好(_user_message)。""" if payload.base_graph and payload.base_graph.get("nodes"): return ( @@ -1089,7 +1160,7 @@ def _graph_request(payload: GenerateIn, *, analysis_tools: bool = True) -> str: f"{json.dumps(_slim(payload.base_graph), ensure_ascii=False, indent=2)}\n\n" f"请按下面的要求修改它(只输出改动操作):\n{payload.instruction}" ) - return _user_message(payload, patch=False, analysis_tools=analysis_tools) + return _user_message(payload, patch=False, analysis_tools=analysis_tools, ontology_tools=ontology_tools) def _start_graph(payload: GenerateIn) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]]]: @@ -1353,7 +1424,7 @@ def _blocking_issues( *, sources: list[Any] | None = None, baseline: list[dict[str, Any]] | None = None, level: str | None = None, defaults: dict[str, Any] | None = None, checkers: dict[str, Any] | None = None, chat_user: bool = False, analysis_tools: bool = True, - off_subgraphs: set[str] | frozenset[str] = frozenset(), + ontology_tools: bool = True, off_subgraphs: set[str] | frozenset[str] = frozenset(), ) -> list[dict[str, Any]] | None: """按运行时同一套校验,挑出会挡住运行的问题。图本身不成形时返回 None。 @@ -1391,7 +1462,8 @@ def _blocking_issues( + _issue_dicts(scope_issues(list(nodes.values()), scope), "datasource_out_of_scope") + [i for i in authored if i["level"] == "error"] + (_chat_user_issues(nodes, edges) if chat_user else []) - + ([] if analysis_tools else _analysis_off_issues(nodes, off_subgraphs))) + + ([] if analysis_tools else _analysis_off_issues(nodes, off_subgraphs)) + + ([] if ontology_tools else _ontology_off_issues(nodes))) if level: from app.engine.governance import lint_for_publish @@ -2140,8 +2212,8 @@ async def _auto_route_ops(payload: GenerateIn) -> list[dict[str, Any]] | None: 搭建者及以上匹配之后直接进程内固定执行;普通 user 先过**资产授权**这道闸(app/apps/access.usable_calibers:授权给它 的应用当前版本钉住的那些口径版本)——命中了但没授权是**终止型结局**(照实说没有授权,不回退旧的 Agent 路径:那条路 会去翻底表),有权则走 prepare 好的父图 + 真实 caliber_query 工具那条路(遮罩与只读由它保证)。命中之后执行失败 - (清单/权限/参数/绑定/超时等)**原样报错、绝不静默回退旧 Agent**;未命中(没匹配到、歧义、参数不全)交回 None, - 调用方照旧走模型那条路,不向用户多说什么、也不澄清。这一段不取助手模型、不读目录、不拼历史——判定本身零模型。""" + (清单/权限/参数/绑定/超时等)**原样报错、绝不静默回退旧 Agent**。已知口径缺语义、参数不足或歧义直接澄清; + 没匹配到或分析问题交回 None,继续探索。用户限定的数据源同样要检查。判定本身不调用模型。""" from app.api.deps import restricted from app.db.base import SessionLocal from app.ledger import nlchange, querycore @@ -2151,15 +2223,30 @@ async def _auto_route_ops(payload: GenerateIn) -> list[dict[str, Any]] | None: async with SessionLocal() as session: # 和旧路径同一道门:请求带的对话读不了先照旧拒(不因为要自动路由就少判一次) await _ensure_conversation_access(session, payload.conversation_id) + selected_sources = await _sources(session, payload.datasource_ids) + allowed_tools = {f"db_query__{source.name}" for source in selected_sources} allowed = await _allowed_calibers(session, principal) routed = await nlchange.auto_route(session, question=_question_of(payload) or payload.instruction, - allowed=allowed) + allowed=allowed, source_tools=allowed_tools if payload.datasource_ids else None) if routed is None: return None if routed.mode == nlchange.ROUTE_REFUSED: return _not_permitted_ops(routed.code) + if routed.mode == nlchange.ROUTE_CLARIFY: + return [{"op": "reply", "text": routed.reason, "route": {"mode": routed.mode, "code": routed.code}}] request = {key: value for key, value in routed.request.items() if key != "purpose"} purpose = str(routed.request.get("purpose") or querycore.DEFAULT_PURPOSE) + if payload.datasource_ids: + from app.ledger import derive + + try: + pinned = await derive.read_pinned(session, request["workflow_id"], request["version"], request["card_id"]) + chosen = derive.select_pinned(pinned, metric_ids=request["metric_ids"]) + except derive.NotDerivable: + return _failed_ops("caliber_unavailable", detail="口径取数依赖尚未就绪", ordinary=ordinary) + if any(tool not in allowed_tools for _, tool, _ in chosen.reads): + return [{"op": "reply", "text": "匹配到的口径使用了当前选择范围之外的数据源,请调整数据源范围或选择其他口径。", + "route": {"mode": "clarify", "code": "source_scope_mismatch"}}] try: outcome = await _execute_route(session, request=request, purpose=purpose, actor=actor, prepared=ordinary, payload=payload) @@ -2171,7 +2258,8 @@ async def _auto_route_ops(payload: GenerateIn) -> list[dict[str, Any]] | None: return [_querycore_final(payload, outcome)] -async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_tools: bool = True): +async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_tools: bool = True, + ontology_tools: bool = True): """生成过程:按需求起草、按需查看、自查修正、排版校验,逐条交出操作(op dict)。问数据页(经 SSE)和评测(直接迭代) 走的是这同一条路(细案 01 做法 2)。 @@ -2243,8 +2331,10 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ except ProviderNotConfigured as e: raise HTTPException(400, _unconfigured(e)) from e - human = _with_history(_graph_request(payload, analysis_tools=analysis_tools), - await _history_section(session, payload.conversation_id)) + human = _with_history( + _graph_request(payload, analysis_tools=analysis_tools, ontology_tools=ontology_tools), + await _history_section(session, payload.conversation_id), + ) # 兜底用:模型只发了改动操作时,把它们重放到这张图上 prev_graph = await _previous_graph(session, payload.conversation_id) # 比对工具绑定的基准:画布上是改之前的图;问数据页是上一轮的图(沿用它的节点 id) @@ -2259,17 +2349,49 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ looks = await _look_service(session, payload, sources, graph=payload.base_graph if ( payload.base_graph or {}).get("nodes") else prev_graph, catalog_view=view, kinds=kinds, caliber=caliber if payload.intent == "answer" else copilot_context.CALIBER_LOOK, - actor=current_principal()) + actor=current_principal(), ontology=ontology_tools) + deep_grounding_note = "" + if payload.intent == "answer" and not chat_user: + from app.chat.grounding import ground_question + + gb = await ground_question( + session, + _question_of(payload), + datasource_ids=payload.datasource_ids, + restricted=False, + ) + extra_blocks: list[str] = [] + if gb.matched_metrics: + m_lines = ["【预命中的独立语义指标卡片(可在 agent 节点的 tools 中绑定 `metric_query` 直接调用)】"] + for mm in gb.matched_metrics: + m_lines.append( + f"- `{mm['key']}`({mm['name']},数据源 `{mm['source_name']}`,底表 `{mm['table_name']}`):" + f"表达式 `{mm['sql_expression']}`" + + (f",时间列 `{mm['date_column']}`" if mm["date_column"] else "") + ) + extra_blocks.append("\n".join(m_lines)) + if gb.matched_entities: + e_lines = ["【预命中的标准业务实体与底层编码映射(写 SQL 或调工具时直接使用)】"] + for me in gb.matched_entities: + binds = ";".join(f"`{b['source_name']}.{b['table_name']}.{b['column_name']}`" for b in me["bindings"]) + e_lines.append(f"- `{me['key']}`({me['label']}):绑定列 {binds}") + for mem in me["matched_members"]: + codes = ",".join(f"{s}=`{c}`" for s, c in mem["resolved_codes"].items()) + if codes: + e_lines.append(f" · 「{mem['matched_term']}」→ 标准成员「{mem['label']}」→ {codes}") + extra_blocks.append("\n".join(e_lines)) + if extra_blocks: + deep_grounding_note = "\n\n" + "\n\n".join(extra_blocks) # 这一份 system 一直用到最后:接着写、自查修正都沿用,不换 system = _graph_system(sources, scope, await copilot_context.section(looks), looks, chat_user=chat_user, - analysis_tools=analysis_tools) + analysis_tools=analysis_tools, ontology_tools=ontology_tools) + deep_grounding_note # 使用者看得见口径但不能选用(K14):模型发了 use_caliber 时照实拒收、自查交回它改用口径查询工具(见 GraphApplier) applier = GraphApplier(nodes, edges, composer=copilot_context.composer(looks), no_compose=chat_user) started = time.monotonic() gen = Generation(model, system=system, applier=applier, looks=looks, started=started, checker=GraphChecker(applier, scope=scope, sources=sources, baseline=baseline, checkers=checkers, chat_user=chat_user, question=_question_of(payload), - analysis_tools=analysis_tools)) + analysis_tools=analysis_tools, ontology_tools=ontology_tools)) async def steps(): yield {"op": "model", "model": model_id} @@ -2337,7 +2459,8 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ yield op off_subgraphs = set() if analysis_tools else await analysis_off_subgraphs(nodes) remaining = _blocking_issues(nodes, edges, scope, sources=sources, baseline=baseline, checkers=checkers, - chat_user=chat_user, analysis_tools=analysis_tools, off_subgraphs=off_subgraphs) + chat_user=chat_user, analysis_tools=analysis_tools, ontology_tools=ontology_tools, + off_subgraphs=off_subgraphs) # 工具绑定变化不挡运行,但要在自查这一步就说出来:工具被改没了的图照样 # 能跑,只是跑出来的是模型「假设」查过库的答案 changes = tool_changes(baseline, list(nodes.values())) @@ -2375,6 +2498,7 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ issues += _chat_user_issues(nodes, edges) if chat_user else [] # 关掉分析工具的那一臂里还绑着分析工具的(自查没改好):同上,照实列出,不运行 issues += [] if analysis_tools else _analysis_off_issues(nodes, off_subgraphs) + issues += [] if ontology_tools else _ontology_off_issues(nodes) # 跳过的节点要说出来,不能安静地少一步。code 给前端认:这一类要单独 # 提示「少了一步」,不能和普通校验警告混在一起 issues += [ @@ -2383,9 +2507,11 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None, analysis_ "message": f"模型使用了不存在的节点类型「{t}」,已跳过这一步"} for t in dict.fromkeys(applier.skipped_types) ] + from app.chat.optimization import prepare as prepare_ask_data + final = { "op": "final", - "graph": spec.model_dump(mode="json"), + "graph": prepare_ask_data(spec.model_dump(mode="json"), _question_of(payload) or payload.instruction), "issues": issues + warnings, "explanation": applier.explanation, "autorun": autorun, @@ -3300,6 +3426,30 @@ async def review_run( model=payload.model, always=payload.always, attempt=payload.attempt) +async def _has_ontology_penetration_candidates(session: AsyncSession, rows: list[Any]) -> bool: + """这次运行若还没走本体穿透(未调用 ontology_neighbors),且工作区存在已确认的已发布本体关联或跨源标准实体桥,则允许提示/升级本体排查。""" + from app.core.events import EventType + from app.data.entities import confirmed_bindings, list_entities + from app.ledger.ontology import build_published_ontology_graph + + for e in rows: + etype = str(getattr(e, "type", "") if not isinstance(e, Mapping) else e.get("type", "")) + data = (getattr(e, "data", None) if not isinstance(e, Mapping) else e.get("data")) or {} + if etype in (EventType.TOOL_START, EventType.TOOL_END) and data.get("tool") == "ontology_neighbors": + return False + try: + ont = await build_published_ontology_graph(session, include_proposed=False) + if ont.get("edges"): + return True + for ent in await list_entities(session): + active = confirmed_bindings(ent) + if len({str(b.get("source_name") or "").lower() for b in active if b.get("source_name")}) >= 2: + return True + except Exception: # noqa: BLE001 + return False + return False + + async def review_of_run(session: AsyncSession, run: Any, *, question: str, provider: str | None = None, model: str | None = None, always: bool = False, attempt: int = 0) -> dict[str, Any]: """复核一次运行(问数据页经 /copilot/review、评测直接调,同一个函数)。 @@ -3316,6 +3466,7 @@ async def review_of_run(session: AsyncSession, run: Any, *, question: str, provi 是交给助手的那句话(chat/turn.retry_instruction),不要是 null。问数据页照它走; - usage:复核这一次模型调用花了多少(providers/usage.py 的汇总,没调模型时是全 0),这一轮的花费 = 助手 + 运行 + 复核。 """ + from app.api.settings import anomaly_escalation_mode from app.chat import turn from app.db.models import RunEvent from app.engine import review as rv @@ -3329,12 +3480,35 @@ async def review_of_run(session: AsyncSession, run: Any, *, question: str, provi signals = rv.scan(rows, output) answer = rv.answer_text(output) spent = usage.meter() + hit_escalation = [s for s in signals if s.kind in rv.ESCALATION_SIGNALS] + can_escalate = bool(hit_escalation) and await _has_ontology_penetration_candidates(session, rows) + esc_mode = await anomaly_escalation_mode(session) if can_escalate else "prompt" def done(result: Any) -> dict[str, Any]: out = result.as_dict() + has_base = turn.has_nodes(run.graph) out["retry_instruction"] = ( - turn.retry_instruction(question, turn.review_reason(out), turn.has_nodes(run.graph)) + turn.retry_instruction(question, turn.review_reason(out), has_base) if turn.retry_after_review(out, attempt) else None) + if can_escalate: + esc_reason = ";".join(s.detail for s in hit_escalation if s.detail) or turn.review_reason(out) + follow_up = turn.escalation_instruction(question, esc_reason, has_base) + auto_esc = esc_mode == "auto" and attempt == 0 + out["anomaly_escalation"] = { + "available": True, + "mode": esc_mode, + "auto_escalate": auto_esc, + "button_label": turn.ESCALATION_BUTTON_LABEL, + "signals": [s.kind for s in hit_escalation], + "reason": esc_reason, + "follow_up_instruction": follow_up, + } + if auto_esc: + out["retry_instruction"] = follow_up + out["escalation"] = True + elif esc_mode == "prompt" and all(s.kind in rv.ESCALATION_SIGNALS for s in signals): + # P1:默认 prompt 模式下,简单查数命中硬异常信号只提示用户一键本体排查,不自动烧额外一轮重跑 + out["retry_instruction"] = None out["usage"] = spent.summary() return out diff --git a/backend/app/api/copilot_context.py b/backend/app/api/copilot_context.py index fa1ea483..06aa24c8 100644 --- a/backend/app/api/copilot_context.py +++ b/backend/app/api/copilot_context.py @@ -110,7 +110,8 @@ SYSTEM_LOOK_UPGRADE_NEED = "要升级的工作流里,查库节点的 SQL 用 async def look_service(sources: list[Any], *, spec: ModelSpec | None, graph: Mapping[str, Any] | None = None, kinds: tuple[str, ...] = ("table", "capability"), answer: bool = False, catalog_view: Any = None, trail: Mapping[str, Any] | None = None, - session: Any = None, actor: Any = None, caliber: str = CALIBER_LOOK) -> LookService: + session: Any = None, actor: Any = None, caliber: str = CALIBER_LOOK, + ontology: bool = True) -> LookService: """按入口组装这一轮的查看服务。读目录、读能力登记都用各自的短会话,开流前后都能调。 spec 是助手的模型规格:挑选模型第一次要用时才按它拿(关思考、额度按 look/pick.PICK_MAX_TOKENS)。graph 是现有工作流,概览里列出它查过的表。 @@ -125,12 +126,13 @@ async def look_service(sources: list[Any], *, spec: ModelSpec | None, graph: Map picker = Picker(spec) made: list[Any] = [] if "table" in kinds: - made.append(await TableKind.load(sources, graph=graph, picker=picker, catalog_view=catalog_view, trail=trail)) + made.append(await TableKind.load(sources, graph=graph, picker=picker, catalog_view=catalog_view, trail=trail, + ontology=ontology)) if "capability" in kinds: made.append(await CapabilityKind.load(picker=picker, read_only=answer)) if "caliber" in kinds and session is not None: made.append(await CaliberKind.load(session, picker=picker, compose=caliber == CALIBER_COMPOSE, actor=actor, - query=caliber == CALIBER_QUERY)) + query=caliber == CALIBER_QUERY, ontology=ontology)) return LookService(made) diff --git a/backend/app/api/copilot_gen.py b/backend/app/api/copilot_gen.py index 1a15b26a..59d93cab 100644 --- a/backend/app/api/copilot_gen.py +++ b/backend/app/api/copilot_gen.py @@ -739,7 +739,7 @@ class GraphChecker: baseline: list[dict[str, Any]] | None = None, level: str | None = None, defaults: dict[str, Any] | None = None, checkers: dict[str, Any] | None = None, known: set[Any] | None = None, chat_user: bool = False, question: str | None = None, - analysis_tools: bool = True) -> None: + analysis_tools: bool = True, ontology_tools: bool = True) -> None: from app.analysis.intent import analysis_intent self.applier = applier @@ -759,6 +759,8 @@ class GraphChecker: self._coverage_given = False #: 这一轮给不给分析工具(评测「关掉分析工具」那一臂为假) self.analysis_tools = analysis_tools + #: 这一轮给不给本体穿透工具(评测「关掉本体穿透」那一臂为假) + self.ontology_tools = ontology_tools #: 关掉分析工具时,用了分析能力的子工作流节点(issues 每次先读好) self._off_subgraphs: set[str] = set() #: 用户问题的分析意图(问为什么、怎么变了、是否异常、趋势……),不是分析类问题、或者这一轮没有分析工具时为 None @@ -772,7 +774,7 @@ class GraphChecker: return _blocking_issues(self.applier.nodes, self.applier.edges, self.scope, sources=self.sources, baseline=self.baseline, level=self.level, defaults=self.defaults, checkers=self.checkers, chat_user=self.chat_user, analysis_tools=self.analysis_tools, - off_subgraphs=self._off_subgraphs) + ontology_tools=self.ontology_tools, off_subgraphs=self._off_subgraphs) async def issues(self) -> list[dict[str, Any]]: if not self.analysis_tools: @@ -890,8 +892,8 @@ def analysis_gaps_fix(*, asked: str = "问题问的是变化从哪来(「把 COVERAGE_BUDGET_S = 8.0 #: 分析类问题、查库的 Agent 没绑分析工具(GraphChecker.analysis_gaps)那条问题的 code ANALYSIS_TOOLS_MISSING = "analysis_tools_missing" -#: 自查让助手绑分析工具时列出的先后:先定现象(可比性、基线、趋势),再拆、再检验(同分析方法 tools/builtin/analysis.py) -ANALYSIS_TOOL_ORDER = ("comparable", "baseline", "trend", "decompose", "differ") +#: 自查让助手绑分析工具时列出的先后:先定现象(可比性、基线、趋势),再拆、再检验、跨源对账与伴随异动(同分析方法 tools/builtin/analysis.py) +ANALYSIS_TOOL_ORDER = ("comparable", "baseline", "trend", "decompose", "differ", "reconcile", "cochange") async def _probe_source(row: Any) -> Any: diff --git a/backend/app/chat/direct.py b/backend/app/chat/direct.py new file mode 100644 index 00000000..52a4aa11 --- /dev/null +++ b/backend/app/chat/direct.py @@ -0,0 +1,275 @@ +"""问数据「快速直查(Fast Direct Ask-Data)」引擎。 + +对比「深度分析(Deep Analysis)」模式: +- 深度分析(ChatDriver):LLM 选表 + 助手规划生成完整多节点画布工作流 → 执行(Agent + Report 二次撰写)→ 运行后 LLM 复核; + 适合复杂归因、跨源本体穿透、正式报告出具。 +- 快速直查(DirectChatDriver):毫秒级确定性语义预命中(Grounding:指标卡片 + 标准业务实体 + 数据目录防错规则,0 LLM) + → 直接编译确定性直查图(q → agent1 → report1 → out1,开启 parallel_tools=True、内联当前东八区时间、单轮内联单元格引用) + → 纯 Python 零模型直通封装 report_doc 数字证据并立即交付答案(0 次额外报告重写调用、0ms 事后复核),同时完整保留可点击数字证据、 + Run 审计记录、SQL 查询快照、只读守卫与敏感列遮罩。 +""" +from __future__ import annotations + +import time +from datetime import datetime, timedelta +from typing import Any +from zoneinfo import ZoneInfo + +from sqlalchemy.ext.asyncio import AsyncSession + +from app.chat.drive import Turn +from app.chat.grounding import GroundingBundle, ground_question +from app.chat.job import ChatDriver, ChatTurnExecution +from app.tools.datasource import QUERY_PREFIX, SCHEMA_PREFIX +from app.tools.metrics import METRIC_QUERY + +_WEEKDAYS_ZH = ("星期一", "星期二", "星期三", "星期四", "星期五", "星期六", "星期日") + + +def _escape_template_braces(text: str) -> str: + """转义预命中文本中可能来自数据库注释的模板括号,防止节点模板渲染器误解析。""" + if not text: + return "" + return text.replace("{{", "{ {").replace("}}", "} }").replace("{%", "{ %").replace("%}", "% }") + + +def _shanghai_time_banner() -> str: + now = datetime.now(ZoneInfo("Asia/Shanghai")) + yesterday = (now.date() - timedelta(days=1)).isoformat() + seven_days_ago = (now.date() - timedelta(days=6)).isoformat() + weekday = _WEEKDAYS_ZH[now.weekday()] + return ( + f"当前东八区时间:{now.strftime('%Y-%m-%d %H:%M:%S')}({weekday});" + f"今天日期:{now.date().isoformat()},昨天日期:{yesterday},近 7 日起点:{seven_days_ago}。" + "(无需再调用时间查询工具)" + ) + + +DIRECT_SYSTEM_PROMPT = """你是 AgentLab 的「快速直查数据分析助手」。你的任务是基于已预命中的指标卡片、标准业务实体与数据目录,以最少的工具轮次、最快速度给出准确、清晰、结构化的 Markdown 数据回答。 + +【核心取数与防错纪律】 +1. **{time_banner}** +2. **优先走标准语义指标**:若下方「已命中的标准语义指标卡片」直接对应用户所问指标,优先调用一次 `metric_query` 获取标准口径结果(支持 `date_from`、`date_to`、`group_by_date`、`group_by`、`filters`)。 +3. **合并查询,杜绝碎片化往返**: + - 手写 `db_query__<源名>` 时,尽量在 **1 条(最多不超过 2 条)SQL** 内一次性查全所需指标与近期对比窗口(例如查「今天怎么样」时,可直接查近 7 天按日汇总 `WHERE stat_date >= '<7日前>' ORDER BY stat_date DESC`,一条 SQL 同时看清今天是否有数、最新到哪一天、以及相比前几天的走势!)。 + - 已开启并行工具调用(`parallel_tools=True`):确实需要查两张互不依赖的表时,在同一轮一次性并行发出工具调用。 +4. **严守标准业务实体与数据目录护栏**: + - 若下方给出了「标准业务实体与物理编码映射」,直接按映射出的列名与底层编码写过滤条件,不要发 `SELECT DISTINCT` 盲猜编码。 + - 严格遵守「数据目录强制防错护栏」中的业务时间列(`business_date`)、有效记录过滤条件(`valid_filter`)以及存量列(`stock`)不可跨期直接求和的约束。 + - 下方「预命中物理表结构」已包含完整字段与目录的表,直接写 SQL,不要重复调 `db_schema__` 查看;只有需要查找未列出的其他表时才用 `db_schema__`(支持传 `keyword` 检索或一次传多个表名)。 +5. **诚实简洁作答与可点击数字证据**: + - 每个数字都必须真实出自本轮工具返回结果,严禁编造或用数据剖析里的估算行数当查询答案。 + - 工具返回头部标有 `【证据 Q1】`、`【证据 Q2】` 等编号:凡是取自查询结果的数值,请直接用单元格引用标记 `[[v:Q1.r0.列名]]` **替代数字本身**(行号从 `r0` 起算;支持 `|万`、`|亿`、`|pct`、`|int`、`|.1` 等换算)。注意:`[[v:...]]` 会直接渲染成数值本身,正确写法为 `总客流 [[v:Q1.r0.total_sys]] 人次`;**严禁**先写裸数字再在后面或句末重复附带 `[[v:...]]`! + - 多行明细优先直接写整表标记 `[[table:Q1]]`(或 `[[table:Q1 cols=列1,列2 rows=0-9]]`),整表内的数字会自动生成可点击证据;真实物理表名用反引号包裹(如 `` `footfall_daily_stat` ``);日期统一写完整 `YYYY-MM-DD`(如 `2026-11-10`)。 + - 需要算合计、差值、占比或环比涨跌幅时,尽量在同一条 SQL 的 `SELECT` 中用 `ROUND(..., 1)` 直接算出结果列并用 `[[v:Q1.r0.列名]]` 引用(不要心算裸写百分比),让派生指标同样具备 SQL 级可点击证据。 + - 若当日数据尚未入库(查询未返回记录),明确写「暂无入库记录」或「未返回记录」(不要手写「0 行」),并主动给出已查到的最新可用日期数据供参考。""" + + +def build_direct_graph( + *, + bundle: GroundingBundle, + has_metrics: bool = True, +) -> dict[str, Any]: + """构建快速直查专用的确定性四节点执行图(input -> agent -> fast_report -> output,报告步 0 次模型调用)。""" + sources = bundle.narrowed_sources or bundle.candidate_sources + tools: list[str] = [] + for ds in sources: + tools.append(f"{QUERY_PREFIX}{ds.name}") + tools.append(f"{SCHEMA_PREFIX}{ds.name}") + if has_metrics: + tools.append(METRIC_QUERY) + tools.extend(["calculator", "kb_search"]) + + base_sys = DIRECT_SYSTEM_PROMPT.format(time_banner=_shanghai_time_banner()) + if bundle.system_context: + full_sys = f"{base_sys}\n\n---\n\n{_escape_template_braces(bundle.system_context)}" + else: + full_sys = base_sys + + user_prompt = ( + "{% if input.history %}【前序对话参考】\n{{ input.history }}\n\n{% endif %}" + "【当前问题】\n{{ input.question }}" + ) + + return { + "nodes": [ + { + "id": "q", + "type": "input", + "position": {"x": 80, "y": 160}, + "data": { + "label": "提问入口", + "config": { + "fields": [ + {"name": "question", "label": "问题", "type": "text", "required": True}, + {"name": "history", "label": "对话上下文", "type": "text", "required": False}, + ] + }, + }, + }, + { + "id": "agent1", + "type": "agent", + "position": {"x": 350, "y": 160}, + "data": { + "label": "快速直查 Agent", + "config": { + "system": full_sys, + "prompt": user_prompt, + "tools": tools, + "parallel_tools": True, + "max_steps": 8, + "ask_data_optimization": 2, + "emit_message": False, + }, + }, + }, + { + "id": "report1", + "type": "report", + "position": {"x": 620, "y": 160}, + "data": { + "label": "零延迟证据核验", + "config": { + "ask_data_optimization": 2, + "reuse_answer_from": "agent1", + "numbers": "off", + "on_violation": "flag", + "max_repairs": 0, + "claims": "off", + "analysis_claims": "off", + "entities": "link", + }, + }, + }, + { + "id": "out1", + "type": "output", + "position": {"x": 890, "y": 160}, + "data": { + "label": "直出回答", + "config": { + "fields": [ + {"name": "answer", "value": "{{ nodes.report1.text }}"}, + ] + }, + }, + }, + ], + "edges": [ + {"id": "q->agent1", "source": "q", "target": "agent1"}, + {"id": "agent1->report1", "source": "agent1", "target": "report1"}, + {"id": "report1->out1", "source": "report1", "target": "out1"}, + ], + } + + +class DirectChatDriver(ChatDriver): + """快速直查驱动:跳过助手建图与事后复核,执行「毫秒级语义预命中 → 确定性直查图运行 → 即时落库」。""" + + def __init__(self, execution: ChatTurnExecution, *, question: str, datasource_ids: list[str]) -> None: + super().__init__(execution, question=question, datasource_ids=datasource_ids) + self.grounding_summary: dict[str, Any] | None = None + + async def launch_args(self, session: AsyncSession, graph: dict[str, Any]) -> dict[str, Any]: + from app.api.deps import restricted + from app.chat.launch import ChatRunRefused, user_chat_run + from app.engine.launch import LaunchRefused + + args: dict[str, Any] = { + "graph": graph, + "actor": self.execution.actor, + "origin_kind": "chat", + "origin": { + "conversation_id": self.execution.conversation_id, + "turn_id": self.execution.turn_id, + "depth": "fast", + }, + } + if restricted(): + try: + args["memory_scope"], args["options"], args["graph"] = await user_chat_run( + session, graph, self.execution.actor + ) + except ChatRunRefused as e: + raise LaunchRefused(403, str(e)) from e + return args + + async def drive( + self, + *, + graph: dict[str, Any] | None = None, + run_id: str | None = None, + retry: bool = True, + instruction: str | None = None, + base_graph: dict[str, Any] | None = None, + ) -> Turn: + from app.api.conversations import run_history + from app.api.deps import restricted + from app.db.base import SessionLocal + + t = self.turn + started = time.monotonic() + try: + if run_id is not None: + await self._phase("run") + t.current_run = run_id + row = await self._follow(run_id) + if row is not None: + t.path = "ran" + return t + + if graph is not None: + self.graph = graph + await self._phase("run") + row = await self._run(graph) + if row is not None: + t.path = "ran" + return t + + # 1. 毫秒级语义预命中(0 次 LLM 调用) + await self._phase("ground") + ground_t0 = time.monotonic() + async with SessionLocal() as session: + history = await run_history( + session, + self.execution.conversation_id, + before_seq=self.execution.turn_seq, + ) + bundle = await ground_question( + session, + self.question, + datasource_ids=self.datasource_ids, + history_text=history, + restricted=restricted(), + ) + t.timings["ground_ms"] = int((time.monotonic() - ground_t0) * 1000) + self.grounding_summary = bundle.ui_summary + + # 2. 构建确定性直查图(含零延迟证据核验)并落库、推送预命中事件 + direct_graph = build_direct_graph(bundle=bundle, has_metrics=True) + if instruction and instruction.strip() and instruction.strip() != self.question.strip(): + # 用户点「重试本轮」且仍保持快速直查时,把重试提示附进用户 prompt + agent_node = next((n for n in direct_graph["nodes"] if n.get("type") == "agent"), None) + if agent_node is not None: + agent_cfg = agent_node["data"]["config"] + agent_cfg["prompt"] = ( + f"{agent_cfg['prompt']}\n\n【重试提示】\n{_escape_template_braces(instruction.strip())}" + ) + self.graph = direct_graph + await self.execution.save( + graph=direct_graph, + explanation="快速直查(语义预命中直连取数)", + meta={"depth": "fast", "grounding": bundle.ui_summary}, + ) + await self.execution.emit("op", {"op": "grounding", "grounding": bundle.ui_summary}) + + # 3. 直接发起运行并流式跟随,结束后零延迟交付(不调报告重写与运行后复核) + await self._phase("run") + payload = {"question": self.question, "history": history} + row = await self._run(direct_graph, payload) + if row is not None: + t.path = "ran" + return t + finally: + t.timings["total_ms"] = int((time.monotonic() - started) * 1000) diff --git a/backend/app/chat/direct_evidence.py b/backend/app/chat/direct_evidence.py new file mode 100644 index 00000000..666422d5 --- /dev/null +++ b/backend/app/chat/direct_evidence.py @@ -0,0 +1,691 @@ +"""快速直查(Fast Direct Ask)零延迟数字证据封装。 + +设计原则: +- 零额外模型调用(0 LLM calls,纯 Python 内存处理 < 5ms),不退回深度模式 25–30s 的二次报告重写; +- 对 Agent 单轮直出文本中的显式标记(`[[v:Q1.r0.col]]`、`[[table:Q1 ...]]`、`[[see:Q1]]`)做容错归一与遮罩守卫, + 杜绝漏写 `.r0.`、列名大小写差异或未解析占位符 `⟦?...⟧` 暴露给用户; +- 对 Agent 未包裹标记但可唯一无歧义回指到未遮罩查询单元格的裸数字(含 Markdown 表格与正文),确定性升级为 + `[[v:Qn.rR.col]]` 引用标记,交由 `compose_doc` 统一生成内容哈希封存的 `report_doc` 工件。 +""" +from __future__ import annotations + +from dataclasses import dataclass +from decimal import Decimal, InvalidOperation, ROUND_HALF_UP +import re +from typing import Any + +from app.core.artifact_store import load as load_artifact +from app.engine.evidence import ( + MARKER_MAX, + MARKER_RE, + TABLE_MAX_COLS, + _INLINE_SEE, + _structural_number, + parse_markers, + placeholder, + resolve_marker, + resolve_support, +) +from app.engine.expressions import cell_value, column_kind +from app.engine.issuance import extract_numbers + +MASKED_WORD = "已遮罩" + +_CELL_REF_RE = re.compile( + r"^(?PQ\d+)\.(?:r(?P\d+)|(?P\d+))\.(?P.+)$", + re.I, +) +_CELL_NOROW_RE = re.compile(r"^(?PQ\d+)\.(?P[^.]+)$", re.I) +_UNSAFE_COL_RE = re.compile(r"[\[\]|\n\r]") +_FENCE_LINE_RE = re.compile(r"^\s*(`{3,}|~{3,})") +_INLINE_CODE_RE = re.compile(r"`+[^`\n]*`+") +_MD_LINK_URL_RE = re.compile(r"\]\([^\)\n]*\)") +_TABLE_SEP_LINE_RE = re.compile(r"^\s*\|[\s:\-|]+\|\s*$") +_ZERO_ROW_COUNT_RE = re.compile(r"^\s*(?:行|条记录|条数据)") + + +@dataclass(frozen=True) +class _CellCandidate: + alias: str + row: int + col: str + dec_value: Decimal + row_keys: tuple[str, ...] + + +@dataclass +class _QueryInfo: + alias: str + artifact: str + columns: list[str] + col_by_lower: dict[str, str] + rows: list[list[Any]] + kinds: list[str | None] + masked_lower: set[str] + + +def _to_decimal(val: Any) -> Decimal | None: + if val is None or isinstance(val, bool): + return None + if isinstance(val, Decimal): + return val if val.is_finite() else None + if isinstance(val, int): + return Decimal(val) + if isinstance(val, float): + if val != val or val in (float("inf"), float("-inf")): + return None + return Decimal(str(val)) + if isinstance(val, str): + s = val.strip() + if not s or s == MASKED_WORD: + return None + try: + d = Decimal(s) + return d if d.is_finite() else None + except InvalidOperation: + return None + return None + + +def _load_query_infos( + catalog: dict[str, Any], + masked_columns: dict[str, Any] | None = None, + loader: Any = None, +) -> dict[str, _QueryInfo]: + read = loader or load_artifact + infos: dict[str, _QueryInfo] = {} + for alias, entry in catalog.items(): + if not isinstance(entry, dict) or entry.get("kind") != "query": + continue + artifact = str(entry.get("artifact") or "") + if not artifact: + continue + try: + snap = read(artifact) + except Exception: # noqa: BLE001 + snap = None + if not isinstance(snap, dict): + continue + cols = [str(c) for c in (snap.get("columns") or [])] + raw_rows = snap.get("rows") or [] + rows: list[list[Any]] = [] + for r in raw_rows: + if isinstance(r, list): + rows.append(r) + elif isinstance(r, tuple): + rows.append(list(r)) + elif isinstance(r, dict): + rows.append([r.get(c) for c in cols]) + kinds = [column_kind(snap, c) for c in cols] + masked_set: set[str] = set() + for mc in snap.get("mask_columns") or []: + if mc: + masked_set.add(str(mc).lower()) + if masked_columns and artifact in masked_columns: + extra = masked_columns[artifact] + for mc in (extra.keys() if isinstance(extra, dict) else extra): + if mc: + masked_set.add(str(mc).lower()) + # 若单元格值在工具边界已被替换为「已遮罩」,整列按遮罩列保护 + for j, c in enumerate(cols): + if any(j < len(r) and r[j] == MASKED_WORD for r in rows): + masked_set.add(c.lower()) + infos[alias] = _QueryInfo( + alias=alias, + artifact=artifact, + columns=cols, + col_by_lower={c.lower(): c for c in cols}, + rows=rows, + kinds=kinds, + masked_lower=masked_set, + ) + return infos + + +def _fenced_line_ranges(text: str) -> list[tuple[int, int]]: + """返回围栏代码块(```...``` / ~~~...~~~)覆盖的字符区间,代码块内不做标记改写与自动回绑。""" + ranges: list[tuple[int, int]] = [] + in_fence = False + fence_char = "" + fence_len = 0 + fence_start = 0 + pos = 0 + for line in text.splitlines(keepends=True): + m = _FENCE_LINE_RE.match(line) + if m: + run = m.group(1) + if not in_fence: + in_fence = True + fence_char = run[0] + fence_len = len(run) + fence_start = pos + elif run[0] == fence_char and len(run) >= fence_len and line[m.end():].strip() == "": + in_fence = False + ranges.append((fence_start, pos + len(line))) + pos += len(line) + if in_fence: + ranges.append((fence_start, len(text))) + return ranges + + +def _in_ranges(idx: int, end: int, ranges: list[tuple[int, int]]) -> bool: + return any(a <= idx and end <= b or (a < end and idx < b) for a, b in ranges) + + +def _normalize_v_marker( + marker: dict[str, Any], + catalog: dict[str, Any], + qinfos: dict[str, _QueryInfo], + loader: Any = None, +) -> str: + ref = str(marker.get("ref") or "").strip() + conv = marker.get("conv") + conv_suffix = f"|{conv}" if conv else "" + + alias = "" + row_idx: int | None = None + col_raw = "" + + m_full = _CELL_REF_RE.match(ref) + if m_full: + q_upper = m_full.group("alias").upper() + alias = q_upper if q_upper in qinfos else m_full.group("alias") + row_idx = int(m_full.group("row") if m_full.group("row") is not None else m_full.group("bare_row")) + col_raw = m_full.group("col").strip() + else: + m_short = _CELL_NOROW_RE.match(ref) + if m_short: + q_upper = m_short.group("alias").upper() + qinfo = qinfos.get(q_upper) + if qinfo and len(qinfo.rows) == 1: + alias = q_upper + row_idx = 0 + col_raw = m_short.group("col").strip() + + if alias and alias in qinfos and row_idx is not None: + qinfo = qinfos[alias] + exact_col = qinfo.col_by_lower.get(col_raw.lower(), col_raw) + if exact_col.lower() in qinfo.masked_lower: + return MASKED_WORD + candidate_raw = f"[[v:{alias}.r{row_idx}.{exact_col}{conv_suffix}]]" + if len(candidate_raw) <= MARKER_MAX: + parsed = parse_markers(candidate_raw) + if parsed: + cite = resolve_marker(parsed[0], catalog, cells_allowed=True, loader=loader) + if cite.get("status") == "resolved": + return candidate_raw + # 若只是换算不兼容(例如文本列写了 |int),退回无换算再试一次 + if conv: + plain_raw = f"[[v:{alias}.r{row_idx}.{exact_col}]]" + parsed_plain = parse_markers(plain_raw) + if parsed_plain: + cite_plain = resolve_marker(parsed_plain[0], catalog, cells_allowed=True, loader=loader) + if cite_plain.get("status") == "resolved": + return plain_raw + + # 原样试试(例如引用的是分析结论 A1.r0.col) + cite_orig = resolve_marker(marker, catalog, cells_allowed=True, loader=loader) + if cite_orig.get("status") == "resolved": + return str(marker["raw"]) + rendered = str(cite_orig.get("rendered") or "") + if rendered and rendered != placeholder(marker["kind"], marker["body"]): + return rendered + return "—" + + +def _normalize_table_marker( + marker: dict[str, Any], + catalog: dict[str, Any], + qinfos: dict[str, _QueryInfo], + loader: Any = None, +) -> str: + ref = str(marker.get("ref") or "").strip() + q_upper = ref.upper() + alias = q_upper if q_upper in qinfos else ref + options = dict(marker.get("options") or {}) + + if alias in qinfos: + qinfo = qinfos[alias] + if not qinfo.rows: + return "(未返回记录)" + if "cols" in options: + wanted_raw = [c.strip() for c in options["cols"].split(",") if c.strip()] + valid_cols = [ + qinfo.col_by_lower[c.lower()] + for c in wanted_raw + if c.lower() in qinfo.col_by_lower and c.lower() not in qinfo.masked_lower + ] + if valid_cols: + options["cols"] = ",".join(valid_cols[:TABLE_MAX_COLS]) + else: + options.pop("cols", None) + else: + unmasked_cols = [c for c in qinfo.columns if c.lower() not in qinfo.masked_lower] + if not unmasked_cols: + return MASKED_WORD + if len(unmasked_cols) < len(qinfo.columns) or len(unmasked_cols) > TABLE_MAX_COLS: + options["cols"] = ",".join(unmasked_cols[:TABLE_MAX_COLS]) + + opt_str = " ".join(f"{k}={v}" for k, v in options.items()) + body = f"{alias} {opt_str}".strip() + candidate_raw = f"[[table:{body}]]" + if len(candidate_raw) <= MARKER_MAX: + parsed = parse_markers(candidate_raw) + if parsed: + cite = resolve_marker(parsed[0], catalog, cells_allowed=True, loader=loader) + if cite.get("status") == "resolved": + return candidate_raw + # 回退到仅保留安全列的基础整表标记 + safe_cols = [ + c for c in qinfo.columns + if c.lower() not in qinfo.masked_lower and c.strip() == c and not _UNSAFE_COL_RE.search(c) + ][:TABLE_MAX_COLS] + if safe_cols: + fallback_raw = ( + f"[[table:{alias}]]" + if len(safe_cols) == len(qinfo.columns) + else f"[[table:{alias} cols={','.join(safe_cols)}]]" + ) + parsed_fb = parse_markers(fallback_raw) + if parsed_fb and resolve_marker(parsed_fb[0], catalog, cells_allowed=True, loader=loader).get("status") == "resolved": + return fallback_raw + + cite_orig = resolve_marker(marker, catalog, cells_allowed=True, loader=loader) + if cite_orig.get("status") == "resolved": + return str(marker["raw"]) + return "" + + +def _sanitize_existing_markers( + text: str, + catalog: dict[str, Any], + qinfos: dict[str, _QueryInfo], + loader: Any = None, +) -> str: + """第一遍:修复与清理模型显式写出的 [[...]] 标记,杜绝未解析占位符和句中 [[see:]] 断句。""" + # 先移除会造成断句的句中 [[see:...]](例如「根据 [[see:Q1]],」->「」) + fences = _fenced_line_ranges(text) + markers = parse_markers(text) + if not markers: + return text + + out: list[str] = [] + last = 0 + for m in markers: + start, end = int(m["start"]), int(m["end"]) + if _in_ranges(start, end, fences): + continue + out.append(text[last:start]) + kind = m["kind"] + if kind == "v": + out.append(_normalize_v_marker(m, catalog, qinfos, loader=loader)) + elif kind == "table": + out.append(_normalize_table_marker(m, catalog, qinfos, loader=loader)) + elif kind == "see": + valid_refs = [ + r for r in (m.get("refs") or []) + if resolve_support(r, catalog, loader=loader).get("status") == "resolved" + ] + if valid_refs: + # 检查周围是否构成句中 _INLINE_SEE 违规,若是则丢弃此标记避免留下「以 为依据」断句 + window = text[max(0, start - 6):min(len(text), end + 6)] + if _INLINE_SEE.search(window): + out.append("") + else: + out.append(f"[[see:{','.join(valid_refs)}]]") + else: + out.append("") + else: + cite = resolve_marker(m, catalog, cells_allowed=True, loader=loader) + if cite.get("status") == "resolved": + out.append(str(m["raw"])) + else: + rendered = str(cite.get("rendered") or "") + if rendered and rendered != placeholder(kind, m["body"]): + out.append(rendered) + elif kind in ("t", "c") and m.get("ref"): + out.append(f"`{m['ref']}`") + else: + out.append("") + last = end + out.append(text[last:]) + return "".join(out) + + +def _build_cell_candidates(qinfos: dict[str, _QueryInfo]) -> list[_CellCandidate]: + candidates: list[_CellCandidate] = [] + for alias, qinfo in qinfos.items(): + for r_idx, row in enumerate(qinfo.rows): + row_keys: list[str] = [] + for j, col in enumerate(qinfo.columns): + if j >= len(row) or col.lower() in qinfo.masked_lower: + continue + val = row[j] + if val is None or isinstance(val, bool): + continue + s = str(val).strip() + if s and s != MASKED_WORD and (_to_decimal(val) is None or qinfo.kinds[j] == "text"): + row_keys.append(s) + if isinstance(val, str) and re.match(r"^\d{4}-\d{2}(?:-\d{2})?", s): + row_keys.append(s[:10]) + keys_tuple = tuple(dict.fromkeys(k for k in row_keys if len(k) >= 2)) + + for j, col in enumerate(qinfo.columns): + if j >= len(row): + continue + if col.lower() in qinfo.masked_lower: + continue + if not col.strip() or col != col.strip() or _UNSAFE_COL_RE.search(col): + continue + kind = qinfo.kinds[j] + if kind == "text": + continue + raw_val = row[j] + parsed_val = cell_value(raw_val, kind) + dec = _to_decimal(parsed_val) + if dec is None: + continue + candidates.append( + _CellCandidate( + alias=alias, + row=r_idx, + col=col, + dec_value=dec, + row_keys=keys_tuple, + ) + ) + return candidates + + +def _table_headers_by_line(lines: list[str]) -> dict[int, list[str]]: + """识别手写 Markdown 表格每行对应的表头列名,辅助同名数值按列对齐消歧。""" + mapping: dict[int, list[str]] = {} + i = 0 + n = len(lines) + while i + 1 < n: + head = lines[i].strip() + sep = lines[i + 1].strip() + if head.startswith("|") and head.endswith("|") and _TABLE_SEP_LINE_RE.match(sep): + headers = [c.strip().strip("`*") for c in head.strip("|").split("|")] + k = i + 2 + while k < n and lines[k].lstrip().startswith("|") and not _TABLE_SEP_LINE_RE.match(lines[k]): + mapping[k] = headers + k += 1 + i = k + continue + i += 1 + return mapping + + +def _auto_bind_bare_numbers( + text: str, + catalog: dict[str, Any], + qinfos: dict[str, _QueryInfo], + loader: Any = None, +) -> str: + """第二遍:对正文中未写标记、但能唯一无歧义匹配未遮罩查询结果单元格的裸数字,自动绑定 [[v:Qn.rR.col]]。""" + cells = _build_cell_candidates(qinfos) + if not cells: + return text + + fences = _fenced_line_ranges(text) + lines = text.splitlines(keepends=True) + table_headers = _table_headers_by_line(lines) + + line_offsets: list[int] = [] + acc = 0 + for ln in lines: + line_offsets.append(acc) + acc += len(ln) + + out_lines: list[str] = [] + for line_idx, line in enumerate(lines): + line_start = line_offsets[line_idx] + line_end = line_start + len(line) + if _in_ranges(line_start, line_end, fences) or _TABLE_SEP_LINE_RE.match(line): + out_lines.append(line) + continue + # 表头行本身不自动替换列名里的数字 + if (line_idx + 1) in table_headers and line.strip().startswith("|"): + out_lines.append(line) + continue + + protected: list[tuple[int, int]] = [] + for m in MARKER_RE.finditer(line): + protected.append((m.start(), m.end())) + for m in _INLINE_CODE_RE.finditer(line): + protected.append((m.start(), m.end())) + for m in _MD_LINK_URL_RE.finditer(line): + protected.append((m.start(), m.end())) + + masked_chars = list(line) + for a, b in protected: + for k in range(max(0, a), min(len(masked_chars), b)): + if masked_chars[k] != "\n": + masked_chars[k] = " " + masked_line = "".join(masked_chars) + + tokens = [ + t for t in extract_numbers(masked_line) + if not _structural_number(masked_line, t) + ] + if not tokens: + out_lines.append(line) + continue + + headers_here = table_headers.get(line_idx) + # 若该行是 Markdown 表格数据行,计算各竖线位置以便定位当前 token 在第几列 + pipe_positions = [idx for idx, ch in enumerate(line) if ch == "|"] if headers_here else [] + + replacements: list[tuple[int, int, str]] = [] + for tok in tokens: + if _in_ranges(tok.start, tok.end, protected): + continue + # 只自动回绑阿拉伯数字(跳过「两天」「三成」等中文数字词) + if not any(ch.isascii() and ch.isdigit() for ch in tok.raw): + continue + # 「0 行」「0 条记录」不绑定到业务数值 0 + if tok.value == 0 and _ZERO_ROW_COUNT_RE.match(line[tok.end:tok.end + 6]): + continue + raw_clean = tok.raw.strip() + unit_conv: str | None = None + unit_scale: Decimal | None = None + if raw_clean.endswith(("万", "亿")) and not raw_clean.endswith("万亿"): + unit_conv = raw_clean[-1] + unit_scale = Decimal(10000) if unit_conv == "万" else Decimal(100_000_000) + num_str = raw_clean[:-1].replace(",", "").strip() + else: + num_str = raw_clean.rstrip("%%").replace(",", "").strip() + target_dec = _to_decimal(num_str) + if target_dec is None: + continue + + matched: list[tuple[_CellCandidate, str | None]] = [] + for cand in cells: + if unit_conv and unit_scale is not None: + scaled_u = cand.dec_value / unit_scale + places = max(int(tok.decimals or 0), 0) + quant = Decimal(1).scaleb(-places) + if scaled_u.quantize(quant, rounding=ROUND_HALF_UP) == target_dec: + matched.append((cand, unit_conv)) + elif cand.dec_value == target_dec: + matched.append((cand, None)) + elif tok.is_percent: + # 单元格存 0.1258,正文写 12.6% 或 12.58% + scaled = cand.dec_value * Decimal(100) + places = max(int(tok.decimals or 0), 0) + quant = Decimal(1).scaleb(-places) + if scaled.quantize(quant, rounding=ROUND_HALF_UP) == target_dec: + matched.append((cand, "pct")) + + if not matched: + continue + + # 多候选消歧:先按同行出现的行键(如日期 2026-11-10、区域名「西区」)收窄 + if len(matched) > 1: + by_row_key = [ + pair for pair in matched + if pair[0].row_keys and any(rk in line for rk in pair[0].row_keys) + ] + if len(by_row_key) == 1: + matched = by_row_key + elif len(by_row_key) > 1: + matched = by_row_key + + # 若仍在 Markdown 表格行内且多列同值,按表头列名精确对齐收窄 + if len(matched) > 1 and headers_here and len(pipe_positions) >= 2: + col_pos = sum(1 for p in pipe_positions if p < tok.start) - 1 + if 0 <= col_pos < len(headers_here): + hdr = headers_here[col_pos].lower() + by_hdr = [pair for pair in matched if pair[0].col.lower() == hdr] + if len(by_hdr) == 1: + matched = by_hdr + + # 只在唯一无歧义命中某一个 (alias, row, col) 时才自动绑定,绝不瞎猜 + unique_locs = {(c.alias, c.row, c.col) for c, _ in matched} + if len(unique_locs) != 1: + continue + + chosen, conv = matched[0] + conv_part = f"|{conv}" if conv else "" + marker_str = f"[[v:{chosen.alias}.r{chosen.row}.{chosen.col}{conv_part}]]" + if len(marker_str) > MARKER_MAX: + continue + parsed = parse_markers(marker_str) + if not parsed: + continue + cite = resolve_marker(parsed[0], catalog, cells_allowed=True, loader=loader) + if cite.get("status") != "resolved": + continue + + rendered = str(cite.get("rendered") or "") + rep_start, rep_end = tok.start, tok.end + # 若原文带 %(如 40%),但无 pct 换算的单元格本身存的是 40、渲染为 "40",保留原文末尾的 % + if tok.is_percent and not rendered.endswith("%") and line[rep_end - 1:rep_end] in ("%", "%"): + rep_end -= 1 + replacements.append((rep_start, rep_end, marker_str)) + + if not replacements: + out_lines.append(line) + continue + + rebuilt: list[str] = [] + cursor = 0 + for a, b, rep in replacements: + if a < cursor: + continue + rebuilt.append(line[cursor:a]) + rebuilt.append(rep) + cursor = b + rebuilt.append(line[cursor:]) + out_lines.append("".join(rebuilt)) + + return "".join(out_lines) + + +_TRAILING_V_CLUSTER_RE = re.compile( + r"(?P[。!?;.!?;])[ \t]*(?P(?:\[\[v:[^\]]+\]\][ \t,,、;;。.]*)+)(?P\r?\n?)$" +) +_ADJACENT_DUP_RE = re.compile( + r"(?[+-]?\d[\d,]*(?:\.\d+)?[%%万亿]?)(?:[ \t]*(?P\[\[v:[^\]]+\]\])|[ \t]*[((][ \t]*(?P\[\[v:[^\]]+\]\])[ \t]*[))])" +) + + +def _comparable_decimal(raw_num: str) -> Decimal | None: + s = raw_num.strip().lstrip("+") + if not s: + return None + if s.endswith(("万", "亿")) and not s.endswith("万亿"): + s = s[:-1].strip() + else: + s = s.rstrip("%%").strip() + return _to_decimal(s.replace(",", "")) + + +def _dedupe_marker_echoes( + text: str, + catalog: dict[str, Any], + loader: Any = None, +) -> str: + """消除模型误把 [[v:...]] 当作脚注追加在裸数字后或句末造成的重复渲染(如 `69,133 [[v:...]]` 或句末堆叠 `。[[v:...]]`)。""" + if "[[v:" not in text: + return text + fences = _fenced_line_ranges(text) + lines = text.splitlines(keepends=True) + acc = 0 + out_lines: list[str] = [] + + for line in lines: + l_start, l_end = acc, acc + len(line) + acc = l_end + if _in_ranges(l_start, l_end, fences) or "[[v:" not in line: + out_lines.append(line) + continue + + # 1) 紧邻重复:`69,133 [[v:Q1.r0.total_sys]]` 或 `69,133([[v:Q1.r0.total_sys]])` + def _collapse_adj(match: re.Match[str]) -> str: + num_txt = match.group("num") + m_txt = match.group("marker") or match.group("pmarker") or "" + d_num = _comparable_decimal(num_txt) + parsed = parse_markers(m_txt) + if d_num is not None and parsed: + cite = resolve_marker(parsed[0], catalog, cells_allowed=True, loader=loader) + if cite.get("status") == "resolved": + d_cite = _comparable_decimal(str(cite.get("rendered") or "")) + if d_cite is not None and d_cite == d_num: + return m_txt + return match.group(0) + + cur = _ADJACENT_DUP_RE.sub(_collapse_adj, line) + + # 2) 句末脚注式堆叠:`... 69,133 ... 50,617。[[v:Q1.r0.a]] [[v:Q1.r0.b]]` + m_tail = _TRAILING_V_CLUSTER_RE.search(cur) + if m_tail: + prefix = cur[: m_tail.start("tail")] + tail_str = m_tail.group("tail") + tail_markers = parse_markers(tail_str) + if tail_markers: + prefix_decs: set[Decimal] = set() + for tok in extract_numbers(prefix): + if any(ch.isascii() and ch.isdigit() for ch in tok.raw): + d = _comparable_decimal(tok.raw) + if d is not None: + prefix_decs.add(d) + for pm in parse_markers(prefix): + c = resolve_marker(pm, catalog, cells_allowed=True, loader=loader) + if c.get("status") == "resolved": + d = _comparable_decimal(str(c.get("rendered") or "")) + if d is not None: + prefix_decs.add(d) + + all_dup = True + for tm in tail_markers: + c = resolve_marker(tm, catalog, cells_allowed=True, loader=loader) + d = _comparable_decimal(str(c.get("rendered") or "")) if c.get("status") == "resolved" else None + if d is None or d not in prefix_decs: + all_dup = False + break + if all_dup: + cur = prefix + m_tail.group("nl") + + out_lines.append(cur) + + return "".join(out_lines) + + +def normalize_and_bind_fast_citations( + raw: str, + catalog: dict[str, Any], + *, + masked_columns: dict[str, Any] | None = None, + loader: Any = None, +) -> str: + """将快速直查 Agent 的输出归一为干净、无未解析标记且自动补齐唯一单元格出处的报告源文本。""" + if not raw or not raw.strip(): + return raw or "" + qinfos = _load_query_infos(catalog, masked_columns=masked_columns, loader=loader) + step1 = _sanitize_existing_markers(raw, catalog, qinfos, loader=loader) + step2 = _dedupe_marker_echoes(step1, catalog, loader=loader) + if not qinfos: + return step2 + return _auto_bind_bare_numbers(step2, catalog, qinfos, loader=loader) diff --git a/backend/app/chat/drive.py b/backend/app/chat/drive.py index 623ce036..54116085 100644 --- a/backend/app/chat/drive.py +++ b/backend/app/chat/drive.py @@ -126,7 +126,8 @@ class TurnDriver: def __init__(self, question: str, *, datasource_ids: list[str], on_phase: Callable[[str], Awaitable[None]] | None = None, - provider: str | None = None, model: str | None = None, analysis_tools: bool = True) -> None: + provider: str | None = None, model: str | None = None, + analysis_tools: bool = True, ontology_tools: bool = True) -> None: self.question = question self.datasource_ids = list(datasource_ids) self.on_phase = on_phase @@ -136,6 +137,8 @@ class TurnDriver: #: 这一轮给不给助手分析工具:透传给 api/copilot.answer_ops 的 analysis_tools。只给评测的「分析工具开、关」对照用 #: (eval/answer.Driver 按变体设),问数据页不暴露这个开关,一直是真 self.analysis_tools = analysis_tools + #: 这一轮给不给助手本体穿透工具与邻居提示(评测「本体穿透开、关」对照用,问数据页一直是真) + self.ontology_tools = ontology_tools self.turn = Turn() self.terminal: dict[str, Any] | None = None self.refusal: Exception | None = None @@ -210,7 +213,8 @@ class TurnDriver: payload = self.generate_in(instruction, base_graph) ops: list[dict[str, Any]] = [] try: - async for op in answer_ops(payload, catalog_view=self.catalog_view(), analysis_tools=self.analysis_tools): + async for op in answer_ops(payload, catalog_view=self.catalog_view(), + analysis_tools=self.analysis_tools, ontology_tools=self.ontology_tools): await self.on_op(op) if op.get("op") in ("thinking", "heartbeat"): continue @@ -435,10 +439,18 @@ class TurnDriver: t.usage["review"] = add_usage(t.usage.get("review"), review.get("usage")) if retry and review.get("retry_instruction"): t.attempts += 1 - t.retries.append(policy.review_reason(review) or "复核判答案不可用") + is_escalation = bool(review.get("escalation")) + t.retries.append( + policy.review_reason(review) + or ("指标触发异常,自动沿本体排查关联数据源" if is_escalation else "复核判答案不可用") + ) instruction = str(review["retry_instruction"]) base_graph = row.graph if policy.has_nodes(row.graph) else None - await self.on_retry(t.retries[-1], kind="review", base_graph=base_graph) + await self.on_retry( + t.retries[-1], + kind="escalation" if is_escalation else "review", + base_graph=base_graph, + ) continue t.path = "ran" return t diff --git a/backend/app/chat/grounding.py b/backend/app/chat/grounding.py new file mode 100644 index 00000000..b8eff3d1 --- /dev/null +++ b/backend/app/chat/grounding.py @@ -0,0 +1,670 @@ +"""问数入口毫秒级确定性语义预命中引擎(Semantic Grounding,0 次模型调用)。 + +把此前分散、未被问数热路径直接利用的三类资产在提问入口一次性打通: +1. **独立语义指标卡片(SemanticMetric)**:按指标名、同义词、描述与词元重合度匹配已启用指标,直接向 Agent 提供 + 标准口径表达式与 `metric_query` 调用指引; +2. **标准业务实体(CanonicalEntity)**:扫描已确认(verified / confirmed)实体的成员名称、别名、源侧编码及实体维度名, + 在 SQL 编写前完成跨源物理表列定位与底层编码确定性消歧(无需 `SELECT DISTINCT` 盲猜); +3. **数据目录与数据剖析(DataCatalog + Profile)**:联合指标底表、实体绑定表与 BM25 表检索(schema_view.TableSearch) + 直选最相关的前若干张物理表(<= 6 张),直接注入字段说明、粒度、业务日期列(business_date)、有效记录过滤条件 + (valid_filter)、存量列禁跨期求和警示(stock)以及剖析最新日期范围,彻底省去建图阶段的 LLM 选表耗时。 + +安全与权限边界: +- 严格遵循 `schema_view.masked_set` / `masked_notes`,敏感遮罩列的注释、码值与剖析范围绝不进入系统上下文或前端摘要; +- 当 `restricted=True`(普通 user 角色)时,`ui_summary` 自动隐去物理表名、物理列名、SQL 表达式与底层编码值,仅展示业务层面的 + 命中指标名、实体名与规则统计。 +""" +from __future__ import annotations + +import re +import time +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +from sqlalchemy import select +from sqlalchemy.ext.asyncio import AsyncSession + +from app.data import catalog, catalog_profile_jobs, schema_view +from app.data.entities import confirmed_bindings, list_entities, translate_entity_value +from app.data.names import name_key +from app.data.semantic_metrics import list_metrics +from app.db.models import DataSource +from app.memory.embeddings import _tokens + +MAX_GROUNDED_METRICS = 5 +MAX_GROUNDED_ENTITIES = 5 +MAX_GROUNDED_TABLES = 6 +MAX_TABLE_DETAIL_CHARS = 18_000 + +_ASCII_WORD_RE = re.compile(r"[a-z0-9_]+", re.IGNORECASE) + + +@dataclass +class GroundingBundle: + elapsed_ms: int = 0 + candidate_sources: list[DataSource] = field(default_factory=list) + narrowed_sources: list[DataSource] = field(default_factory=list) + matched_metrics: list[dict[str, Any]] = field(default_factory=list) + matched_entities: list[dict[str, Any]] = field(default_factory=list) + matched_tables: list[dict[str, Any]] = field(default_factory=list) + guardrails: list[dict[str, str]] = field(default_factory=list) + system_context: str = "" + ui_summary: dict[str, Any] = field(default_factory=dict) + + +def _term_in_text(term: str, text_lower: str, ascii_words: set[str]) -> bool: + clean = str(term or "").strip().lower() + if not clean: + return False + # 纯 ASCII 短词要求整词边界匹配,防止如 "id"、"pv"、"l1" 误中长英文串内部 + if clean.isascii() and re.fullmatch(r"[a-z0-9_]+", clean): + if len(clean) < 2: + return False + return clean in ascii_words or (len(clean) >= 4 and clean in text_lower) + if len(clean) < 2: + return False + return clean in text_lower + + +def _match_entities_fast( + entities: Sequence[Any], + *, + question: str, + allowed_source_names: set[str], +) -> list[dict[str, Any]]: + text_lower = question.lower() + ascii_words = {m.group(0).lower() for m in _ASCII_WORD_RE.finditer(question)} + hits: list[tuple[int, dict[str, Any]]] = [] + + for ent in entities: + active_bindings = [ + b + for b in confirmed_bindings(ent) + if not allowed_source_names or name_key(str(b.get("source_name") or "")) in allowed_source_names + ] + if not active_bindings: + continue + + # 1) 优先匹配具体成员值(如「西区」「L2产线」「静安寺店」) + matched_members: list[dict[str, Any]] = [] + for m in ent.members or []: + if not isinstance(m, Mapping): + continue + m_val = str(m.get("value") or "").strip() + m_label = str(m.get("label") or m_val).strip() + raw_source_codes = m.get("source_codes") if isinstance(m.get("source_codes"), Mapping) else {} + flat_codes = [ + str(x).strip() + for c in raw_source_codes.values() + for x in (c if isinstance(c, (list, tuple, set)) else [c]) + if str(x or "").strip() + ] + candidate_terms = [ + m_label, + m_val, + *(str(a) for a in (m.get("aliases") or []) if a), + *flat_codes, + ] + hit_term = next((t for t in candidate_terms if _term_in_text(t, text_lower, ascii_words)), None) + if hit_term: + resolved_by_source: dict[str, str] = {} + target_codes_by_source: dict[str, list[str]] = {} + for b in active_bindings: + sname = str(b.get("source_name") or "") + translated = translate_entity_value(ent, m_val, to_source=sname) + if translated is not None: + target_val = ( + str(translated.get("target_value") or "").strip() + if isinstance(translated, Mapping) + else str(translated).strip() + ) + if target_val: + resolved_by_source[sname] = target_val + target_codes_by_source[sname] = [target_val] + matched_members.append( + { + "member_id": str(m.get("id") or ""), + "matched_term": hit_term, + "value": m_val, + "label": m_label, + "canonical_value": m_val, + "canonical_label": m_label, + "resolved_codes": resolved_by_source, + "target_codes": target_codes_by_source, + } + ) + + # 2) 再匹配实体维度名本身(如「各产线」「按门店」「分区域」) + ent_terms = [str(ent.label or ""), str(ent.key or ""), *(str(a) for a in (ent.aliases or []) if a)] + dim_hit_term = next((t for t in ent_terms if _term_in_text(t, text_lower, ascii_words)), None) + + if not matched_members and not dim_hit_term: + continue + + score = (20 * len(matched_members)) + (8 if dim_hit_term else 0) + hits.append( + ( + score, + { + "id": ent.id, + "key": ent.key, + "label": ent.label, + "matched_term": matched_members[0]["matched_term"] if matched_members else (dim_hit_term or ent.label), + "matched_members": matched_members[:4], + "bindings": [ + { + "source_id": b.get("source_id"), + "source_name": str(b.get("source_name") or ""), + "table_name": str(b.get("table_name") or ""), + "column_name": str(b.get("column_name") or ""), + } + for b in active_bindings[:6] + ], + }, + ) + ) + + hits.sort(key=lambda pair: (-pair[0], pair[1]["key"])) + return [item for _, item in hits[:MAX_GROUNDED_ENTITIES]] + + +def _match_metrics_fast( + metrics: Sequence[Any], + *, + question: str, + source_map: Mapping[str, DataSource], +) -> list[dict[str, Any]]: + if not metrics: + return [] + text_lower = question.lower() + ascii_words = {m.group(0).lower() for m in _ASCII_WORD_RE.finditer(question)} + q_tokens = set(_tokens(question)) + + scored: list[tuple[float, dict[str, Any]]] = [] + for row in metrics: + ds = source_map.get(row.source_id) + if ds is None: + continue + score = 0.0 + matched_by: list[str] = [] + if _term_in_text(row.key, text_lower, ascii_words): + score += 14.0 + matched_by.append(row.key) + if _term_in_text(row.name, text_lower, ascii_words): + score += 12.0 + matched_by.append(row.name) + for alias in row.aliases or []: + if _term_in_text(str(alias), text_lower, ascii_words): + score += 10.0 + matched_by.append(str(alias)) + break + + doc_str = " ".join([row.name or "", " ".join(str(a) for a in (row.aliases or [])), row.description or "", row.table_name or ""]) + m_tokens = set(_tokens(doc_str)) + overlap = len(q_tokens & m_tokens) + if overlap >= 2: + score += min(6.0, overlap * 1.2) + # 若数据源名本身也在问题里出现,给该源下的相关指标轻微加权 + if _term_in_text(ds.name, text_lower, ascii_words) and overlap >= 1: + score += 2.5 + + if score < 3.5: + continue + + scored.append( + ( + score, + { + "id": row.id, + "key": row.key, + "name": row.name, + "unit": row.unit or "", + "description": row.description or "", + "source_id": ds.id, + "source_name": ds.name, + "calc_mode": getattr(row, "calc_mode", None) or "expression", + "table_name": row.table_name, + "sql_expression": row.sql_expression, + "date_column": row.date_column or "", + "filter_sql": row.filter_sql or "", + "dimensions": list(row.dimensions or []), + "matched_term": matched_by[0] if matched_by else row.name, + "score": round(score, 2), + }, + ) + ) + + scored.sort(key=lambda pair: (-pair[0], pair[1]["key"])) + return [item for _, item in scored[:MAX_GROUNDED_METRICS]] + + +def _extract_table_guardrails( + source_name: str, + table_name: str, + visible_notes: Mapping[str, Any], + masked: set[str], +) -> list[dict[str, Any]]: + out: list[dict[str, Any]] = [] + t_label = str((visible_notes.get("label") or {}).get("value") or "").strip() if isinstance(visible_notes.get("label"), Mapping) else "" + display_tbl = f"{source_name}.{table_name}" + (f"({t_label})" if t_label else "") + + b_date = visible_notes.get("business_date") + if isinstance(b_date, Mapping) and b_date.get("value"): + b_val = b_date["value"] + if isinstance(b_val, Mapping): + col = str(b_val.get("column") or "").strip() + rule_extra = str(b_val.get("rule") or "").strip() + else: + col = str(b_val or "").strip() + rule_extra = "" + if col and col.lower() not in masked: + rule_str = f"业务时间列:{col}" + (f"({rule_extra})" if rule_extra else "") + out.append( + { + "kind": "business_date", + "table": display_tbl, + "column": col, + "rule": rule_str, + "note": rule_str, + } + ) + + v_filt = visible_notes.get("valid_filter") + if isinstance(v_filt, Mapping) and v_filt.get("value"): + cond = str(v_filt["value"]).strip() + rule_str = f"有效记录过滤:{cond}" + out.append( + { + "kind": "valid_filter", + "table": display_tbl, + "filter": cond, + "rule": rule_str, + "note": rule_str, + } + ) + + cols = visible_notes.get("columns") + if isinstance(cols, Mapping): + stock_cols: list[str] = [] + for cname, citems in cols.items(): + if str(cname).lower() in masked or not isinstance(citems, Mapping): + continue + m_item = citems.get("measure") + if isinstance(m_item, Mapping) and str(m_item.get("value") or "") == "stock": + stock_cols.append(str(cname)) + if stock_cols: + rule_str = f"存量列(禁跨日直接 SUM):{', '.join(stock_cols[:5])}" + out.append( + { + "kind": "stock_columns", + "table": display_tbl, + "columns": stock_cols[:8], + "rule": rule_str, + "note": rule_str, + } + ) + return out + + +async def ground_question( + session: AsyncSession, + question: str, + *, + datasource_ids: Sequence[str] | None = None, + history_text: str = "", + restricted: bool = False, +) -> GroundingBundle: + """在问数入口毫秒级同步完成「指标卡片 + 业务实体 + 数据目录」三重语义预命中。""" + t0 = time.perf_counter() + stmt = select(DataSource).where(DataSource.enabled.is_(True)).order_by(DataSource.name.asc()) + all_enabled = list((await session.execute(stmt)).scalars().all()) + if not all_enabled: + return GroundingBundle(elapsed_ms=int((time.perf_counter() - t0) * 1000)) + + if datasource_ids: + wanted = {str(x).strip() for x in datasource_ids if str(x).strip()} + wanted_lower = {x.lower() for x in wanted} + candidate_sources = [ + ds for ds in all_enabled if ds.id in wanted or ds.name in wanted or ds.name.lower() in wanted_lower + ] + else: + candidate_sources = list(all_enabled) + + if not candidate_sources: + return GroundingBundle(elapsed_ms=int((time.perf_counter() - t0) * 1000)) + + source_by_id = {ds.id: ds for ds in candidate_sources} + allowed_source_keys = {name_key(ds.name) for ds in candidate_sources} + + # 合并当前问题与上一轮简短上下文用于消歧指代(权重以当前问题为主) + combined_q = question.strip() + if history_text and len(combined_q) < 24: + combined_q = f"{combined_q}\n{history_text[-300:]}" + + q_lower = question.lower() + q_ascii = {m.group(0).lower() for m in _ASCII_WORD_RE.finditer(question)} + + # 1. 识别用户是否显式点名了某个数据源(如 "zhangyuan 今天客流咋样") + explicit_sources = [ + ds + for ds in candidate_sources + if _term_in_text(ds.name, q_lower, q_ascii) + or (ds.description and len(ds.description.strip()) >= 2 and ds.description.strip().lower() in q_lower) + ] + + # 2. 标准业务实体匹配 + all_entities = await list_entities(session) + matched_entities = _match_entities_fast( + all_entities, + question=combined_q, + allowed_source_names=allowed_source_keys, + ) + + # 3. 启用态独立语义指标匹配 + enabled_metrics = await list_metrics(session, status="enabled") + if explicit_sources: + exp_ids = {ds.id for ds in explicit_sources} + scoped_metrics = [m for m in enabled_metrics if m.source_id in exp_ids] or enabled_metrics + else: + scoped_metrics = [m for m in enabled_metrics if m.source_id in source_by_id] + matched_metrics = _match_metrics_fast(scoped_metrics, question=combined_q, source_map=source_by_id) + + # 4. 收敛本轮优先挂载与检索的数据源集合 + if datasource_ids: + narrowed_sources = list(candidate_sources) + elif explicit_sources: + extra_ids = {m["source_id"] for m in matched_metrics} + narrowed_sources = list(explicit_sources) + [ + ds for ds in candidate_sources if ds.id in extra_ids and ds not in explicit_sources + ] + else: + narrowed_sources = list(candidate_sources) + + # 5. 数据目录 BM25 直选 + 指标底表 + 实体绑定表 -> 组装高信噪比表结构与防错护栏 + matched_tables: list[dict[str, Any]] = [] + guardrails: list[dict[str, str]] = [] + table_blocks: list[str] = [] + total_detail_chars = 0 + + for ds in narrowed_sources: + cache = ds.schema_cache if isinstance(ds.schema_cache, Mapping) else {} + tables_map = (cache.get("tables") or {}) if isinstance(cache, Mapping) else {} + if not isinstance(tables_map, Mapping) or not tables_map: + continue + + entries = await catalog.read_catalog(session, ds.id) + raw_notes = {t: e.notes for t, e in entries.items()} + visible_by_table = {t: catalog.visible_notes(e.notes) for t, e in entries.items()} + try: + facts = await catalog_profile_jobs.last_facts(session, ds.id) + except Exception: # noqa: BLE001 + facts = {} + + picked_for_ds: list[str] = [] + reasons_for_table: dict[str, str] = {} + + # (a) 命中指标的底表优先入选 + for mm in matched_metrics: + if mm["source_id"] == ds.id: + resolved = catalog.resolve_table_name(cache, mm["table_name"]) + if resolved and resolved not in picked_for_ds: + picked_for_ds.append(resolved) + reasons_for_table[resolved] = f"指标「{mm['name']}」底表" + + # (b) 命中实体的绑定表入选 + for me in matched_entities: + for b in me["bindings"]: + if name_key(b["source_name"]) == name_key(ds.name): + resolved = catalog.resolve_table_name(cache, b["table_name"]) + if resolved and resolved not in picked_for_ds and len(picked_for_ds) < MAX_GROUNDED_TABLES: + picked_for_ds.append(resolved) + reasons_for_table[resolved] = f"实体「{me['label']}」绑定表" + + # (c) BM25 数据目录检索直选(0 LLM 调用) + remaining_slots = MAX_GROUNDED_TABLES - len(matched_tables) - len(picked_for_ds) + if remaining_slots > 0: + hits = schema_view.search_tables(ds, visible_by_table, combined_q, limit=remaining_slots + 2) + for h in hits: + if h.in_scope and h.name not in picked_for_ds and len(picked_for_ds) + len(matched_tables) < MAX_GROUNDED_TABLES: + picked_for_ds.append(h.name) + reasons_for_table[h.name] = "目录语义检索命中" + + # (d) 若用户明确指定了该小库(<= 5 张表)且尚未命中任何表,直接全给 + if not picked_for_ds and ds in explicit_sources and len(tables_map) <= 5: + for tname in list(tables_map.keys())[:MAX_GROUNDED_TABLES - len(matched_tables)]: + picked_for_ds.append(tname) + reasons_for_table[tname] = "指定数据源核心表" + + if not picked_for_ds: + continue + + # 补一跳连接中间表(若有) + try: + rel_graph = schema_view.relation_graph(ds, raw_notes) + completed_tables, _ = schema_view.complete(picked_for_ds, rel_graph, room=1) + except Exception: # noqa: BLE001 + rel_graph = {} + completed_tables = picked_for_ds + + masked = schema_view.masked_set(ds) + ds_sections: list[str] = [f"### 数据源 `{ds.name}`({ds.kind})预命中表与目录"] + for tname in completed_tables: + if len(matched_tables) >= MAX_GROUNDED_TABLES + 1: + break + v_notes = visible_by_table.get(tname) or {} + t_label = str((v_notes.get("label") or {}).get("value") or "").strip() if isinstance(v_notes.get("label"), Mapping) else "" + t_grain = str((v_notes.get("grain") or {}).get("value") or "").strip() if isinstance(v_notes.get("grain"), Mapping) else "" + raw_bdate = (v_notes.get("business_date") or {}).get("value") if isinstance(v_notes.get("business_date"), Mapping) else None + t_bdate = ( + str(raw_bdate.get("column") or "").strip() + if isinstance(raw_bdate, Mapping) + else str(raw_bdate or "").strip() + ) + t_vfilt = str((v_notes.get("valid_filter") or {}).get("value") or "").strip() if isinstance(v_notes.get("valid_filter"), Mapping) else "" + matched_tables.append( + { + "datasource_id": ds.id, + "datasource_name": ds.name, + "source_id": ds.id, + "source_name": ds.name, + "table_name": tname, + "label": t_label, + "grain": t_grain, + "business_date": t_bdate, + "valid_filter": t_vfilt, + "reason": reasons_for_table.get(tname, "关联中间表"), + } + ) + guardrails.extend(_extract_table_guardrails(ds.name, tname, v_notes, masked)) + + if total_detail_chars < MAX_TABLE_DETAIL_CHARS: + detail = schema_view.table_detail(ds, tname, catalog_notes=raw_notes, profile=facts) + total_detail_chars += len(detail) + ds_sections.append(detail) + else: + ds_sections.append(schema_view.table_brief(ds, tname)) + + # 若该源有多张表入选,附上已确认/推断的 JOIN 条件 + if len(completed_tables) >= 2 and rel_graph: + qual = schema_view.qualifier(ds) + edges = schema_view._edges_within(rel_graph, completed_tables) + if edges: + join_lines = [f" - {schema_view._edge_line(e, qual)}" for e in edges[:10]] + ds_sections.append("表间标准连接条件:\n" + "\n".join(join_lines)) + + table_blocks.append("\n".join(ds_sections)) + if len(matched_tables) >= MAX_GROUNDED_TABLES: + break + + elapsed_ms = max(1, int((time.perf_counter() - t0) * 1000)) + + # 6. 组装注入给直查 Agent 的高密度语义上下文 + ctx_parts: list[str] = [] + if matched_metrics: + m_lines = ["## 一、已命中的标准语义指标卡片(优先调 `metric_query` 工具直接取数)"] + for mm in matched_metrics: + dims_desc = "、".join( + f"{d.get('key')}({d.get('label')}" + (f"→实体:{d.get('entity_key')}" if d.get("entity_key") else "") + ")" + for d in (mm.get("dimensions") or []) + if isinstance(d, Mapping) + ) or "无" + mode_tag = "|模式:多表参数化 SQL 模板(必须调用 `metric_query` 执行,勿手写跨表拼凑)" if mm.get("calc_mode") == "sql_template" else "" + m_lines.append( + f"- 指标 `{mm['key']}`|名称:{mm['name']}" + + (f"(单位:{mm['unit']})" if mm["unit"] else "") + + f"|数据源:`{mm['source_name']}`|底表:`{mm['table_name']}`{mode_tag}" + + (f"|时间列:`{mm['date_column']}`" if mm["date_column"] else "") + + f"\n 口径表达式:`{mm['sql_expression']}`" + + (f"|有效过滤:`{mm['filter_sql']}`" if mm["filter_sql"] else "") + + f"|可分组/过滤维度:{dims_desc}" + ) + if mm["description"]: + m_lines.append(f" 口径说明:{mm['description']}") + ctx_parts.append("\n".join(m_lines)) + + if matched_entities: + e_lines = ["## 二、已命中的标准业务实体与物理编码映射(写 WHERE 条件或调工具时直接使用,勿盲猜编码)"] + for me in matched_entities: + bind_desc = ";".join( + f"`{b['source_name']}.{b['table_name']}.{b['column_name']}`" for b in me["bindings"] + ) + e_lines.append(f"- 标准实体 `{me['key']}`({me['label']})|物理列绑定:{bind_desc}") + for mem in me["matched_members"]: + codes_str = ",".join(f"{s}=`{c}`" for s, c in mem["resolved_codes"].items()) or f"标准值=`{mem['value']}`" + e_lines.append(f" · 提问词「{mem['matched_term']}」→ 标准成员「{mem['label']}」→ 各库底层编码:{codes_str}") + ctx_parts.append("\n".join(e_lines)) + + if guardrails: + g_lines = ["## 三、数据目录强制防错护栏(写 SQL 时必须遵守)"] + for g in guardrails[:12]: + g_lines.append(f"- `{g['table']}`:{g['rule']}") + ctx_parts.append("\n".join(g_lines)) + + if table_blocks: + ctx_parts.append("## 四、预命中物理表结构、数据目录与剖析范围(可直接据此写 SQL,无需再调 db_schema 查看以下表)\n" + "\n\n".join(table_blocks)) + + # 补充候选数据源概览,便于预命中未覆盖时 Agent 按需使用 db_schema__ + if len(narrowed_sources) > 0: + overview = [ + f"- `{ds.name}`({ds.kind}):共 {len(((ds.schema_cache or {}).get('tables') or {}))} 张已探查表" + + (f" — {ds.description}" if ds.description else "") + for ds in narrowed_sources + ] + ctx_parts.append("## 五、本轮可用数据源清单\n" + "\n".join(overview)) + + # 7. 组装前端可观测摘要(restricted=True 时隐去物理表名、列名与底层编码) + if restricted: + ui_metrics = [ + { + "id": m["id"], + "key": m["key"], + "name": m["name"], + "unit": m["unit"], + "datasource_id": m["source_id"], + "datasource_name": m["source_name"], + "source_name": m["source_name"], + } + for m in matched_metrics + ] + ui_entities = [ + { + "entity_id": e["id"], + "entity_key": e["key"], + "key": e["key"], + "label": e["label"], + "matched_member": ( + { + "canonical_value": e["matched_members"][0]["value"], + "canonical_label": e["matched_members"][0]["label"], + "matched_term": e["matched_members"][0]["matched_term"], + } + if e["matched_members"] + else None + ), + "matched_members": [{"label": mem["label"]} for mem in e["matched_members"]], + } + for e in matched_entities + ] + ui_tables = [ + { + "datasource_id": t["datasource_id"], + "datasource_name": t["datasource_name"], + "source_name": t["source_name"], + "table_name": t["label"] or "业务数据表", + "label": t["label"] or "业务数据表", + "reason": t["reason"], + } + for t in matched_tables + ] + ui_guardrails = [ + { + "kind": g["kind"], + "rule": "已应用数据目录有效口径与汇总约束", + "note": "已应用数据目录有效口径与汇总约束", + } + for g in guardrails[:4] + ] + else: + ui_metrics = [ + { + "id": m["id"], + "key": m["key"], + "name": m["name"], + "unit": m["unit"], + "calc_mode": m.get("calc_mode", "expression"), + "datasource_id": m["source_id"], + "datasource_name": m["source_name"], + "source_name": m["source_name"], + "table_name": m["table_name"], + "sql_expression": m["sql_expression"], + "date_column": m["date_column"], + } + for m in matched_metrics + ] + ui_entities = [ + { + "entity_id": e["id"], + "entity_key": e["key"], + "key": e["key"], + "label": e["label"], + "matched_member": ( + { + "member_id": e["matched_members"][0].get("member_id", ""), + "canonical_value": e["matched_members"][0]["value"], + "canonical_label": e["matched_members"][0]["label"], + "matched_term": e["matched_members"][0]["matched_term"], + "target_codes": e["matched_members"][0]["target_codes"], + } + if e["matched_members"] + else None + ), + "matched_members": e["matched_members"], + "bound_columns": e["bindings"], + "bindings": e["bindings"], + } + for e in matched_entities + ] + ui_tables = matched_tables + ui_guardrails = guardrails[:8] + + ui_summary = { + "elapsed_ms": elapsed_ms, + "metrics": ui_metrics, + "entities": ui_entities, + "tables": ui_tables, + "guardrails": ui_guardrails, + "narrowed_sources": [{"id": ds.id, "name": ds.name} for ds in narrowed_sources], + } + + return GroundingBundle( + elapsed_ms=elapsed_ms, + candidate_sources=candidate_sources, + narrowed_sources=narrowed_sources, + matched_metrics=matched_metrics, + matched_entities=matched_entities, + matched_tables=matched_tables, + guardrails=guardrails, + system_context="\n\n".join(ctx_parts), + ui_summary=ui_summary, + ) diff --git a/backend/app/chat/job.py b/backend/app/chat/job.py index 9a6c65b0..2df64e74 100644 --- a/backend/app/chat/job.py +++ b/backend/app/chat/job.py @@ -59,9 +59,9 @@ from app.db.base import SessionLocal, current_owner, utcnow logger = logging.getLogger(__name__) -#: 发起一轮的几种方式:ask 新问;retry 重试本轮(带着上一次的原因重建);rerun 原图重新运行;max_steps 放宽步数重新运行; -#: run 只建了图、用户点「运行」;continue 从断点接着跑(失败的、服务重启挂起的);resume 接着等这一轮的那次运行、复核收尾 -MODES = ("ask", "retry", "rerun", "max_steps", "run", "continue", "resume") +#: 发起一轮的几种方式:ask 新问;retry 重试本轮(带着上一次的原因重建);escalate 沿本体排查关联数据源升级重跑;rerun 原图重新运行; +#: max_steps 放宽步数重新运行;run 只建了图、用户点「运行」;continue 从断点接着跑(失败的、服务重启挂起的);resume 接着等这一轮的那次运行、复核收尾 +MODES = ("ask", "retry", "escalate", "rerun", "max_steps", "run", "continue", "resume") #: 复核之后会自动重来的方式(用户点的「重新运行」「跑一下」「继续运行」照以前不自动重来) AUTO_RETRY_MODES = ("ask", "retry") #: 并发类别(第 2 波按它给上限和优先级) @@ -197,7 +197,7 @@ class ChatDriver(TurnDriver): from app.chat import turn as policy # 换下来的那次运行交出去并进 earlier;这一次从「还没有运行」起,收尾时不再把它当这一次的运行记一遍 - run, self.last_run = (self.last_run if kind == "review" else None), None + run, self.last_run = (self.last_run if kind in ("review", "escalation") else None), None await self.execution.retrying(reason, kind=kind, base=policy.has_nodes(base_graph), attempt=self.turn.attempts, run=run, detail=detail) @@ -214,8 +214,11 @@ class ChatDriver(TurnDriver): from app.api.deps import restricted from app.chat.launch import ChatRunRefused, user_chat_run from app.engine.launch import LaunchRefused + from app.chat.optimization import prepare - args: dict[str, Any] = {"actor": self.execution.actor, "origin_kind": "chat", + graph = prepare(graph, self.question) + + args: dict[str, Any] = {"graph": graph, "actor": self.execution.actor, "origin_kind": "chat", "origin": {"conversation_id": self.execution.conversation_id, "turn_id": self.execution.turn_id}} if restricted(): @@ -413,7 +416,14 @@ class ChatTurnExecution(runtime.JobRun): return set_principal(principal) scope = [s.get("id") for s in self.request.get("scope") or [] if isinstance(s, Mapping) and s.get("id")] - driver = self.driver = ChatDriver(self, question=row.question, datasource_ids=scope) + req_depth = str(self.request.get("depth") or "").strip().lower() + if req_depth == "fast" and self.mode != "escalate": + from app.chat.direct import DirectChatDriver + + driver: ChatDriver = DirectChatDriver(self, question=row.question, datasource_ids=scope) + else: + driver = ChatDriver(self, question=row.question, datasource_ids=scope) + self.driver = driver driver.turn.attempts = int(job.attempt or 0) retry = self.mode in AUTO_RETRY_MODES graph = row.graph if policy.has_nodes(row.graph) else None @@ -425,7 +435,7 @@ class ChatTurnExecution(runtime.JobRun): graph = record.with_max_steps(graph, int(self.request.get("max_steps") or 0)) await self.save(graph=graph) await driver.drive(graph=graph, retry=False) - elif self.mode == "retry": + elif self.mode in ("retry", "escalate"): await driver.drive(instruction=str(self.request.get("instruction") or row.question), base_graph=graph if self.request.get("base") else None) else: @@ -683,7 +693,7 @@ def _timing(request: Mapping[str, Any]) -> dict[str, Any]: async def _queries(run_id: str | None) -> int | None: - """这次运行查了几次库(db_query 的每一次调用,同页面的 countQueries)。""" + """这次运行查了几次库(db_query / metric_query / caliber_query 的每一次调用,同页面的 countQueries)。""" from app.core.events import EventType from app.db.models import RunEvent @@ -692,7 +702,15 @@ async def _queries(run_id: str | None) -> int | None: async with SessionLocal() as session: rows = (await session.execute(select(RunEvent.data).where( RunEvent.run_id == run_id, RunEvent.type == EventType.TOOL_START))).scalars().all() - return sum(1 for d in rows if isinstance(d, dict) and str(d.get("tool") or "").startswith("db_query")) + return sum( + 1 + for d in rows + if isinstance(d, dict) + and ( + str(d.get("tool") or "").startswith("db_query") + or str(d.get("tool") or "") in ("metric_query", "caliber_query") + ) + ) async def _rejected_by(run_id: str) -> dict[str, Any]: @@ -890,7 +908,7 @@ async def hold_conversation(session: AsyncSession, conversation_id: str, *, touc async def start(session: AsyncSession, *, conversation: Any, question: str, datasource_ids: list[str] | None, actor: str | None, mode: str | None = None, retry_of: Any = None, - max_steps: int | None = None) -> str: + max_steps: int | None = None, depth: str | None = None) -> str: """发起一轮(新问,或者对已有的一轮重试、重新运行、继续运行、接着收尾)。交回这一轮的 id(conversation_turns.id)。 新问:建 conversation_turns 那一行(同 POST /api/conversations/{id}/turns)和任务。已有的一轮:上一次的结局归档进 @@ -929,7 +947,7 @@ async def start(session: AsyncSession, *, conversation: Any, question: str, data try: turn_id, stale_run = await _claim(session, conversation=conversation, question=question, datasource_ids=datasource_ids, actor=actor, mode=mode, retry_of=retry_of, - max_steps=max_steps) + max_steps=max_steps, depth=depth) except BaseException: await session.rollback() if continued: @@ -962,7 +980,8 @@ async def start(session: AsyncSession, *, conversation: Any, question: str, data async def _claim(session: AsyncSession, *, conversation: Any, question: str, datasource_ids: list[str] | None, - actor: str | None, mode: str, retry_of: Any, max_steps: int | None) -> tuple[str, str | None]: + actor: str | None, mode: str, retry_of: Any, max_steps: int | None, + depth: str | None = None) -> tuple[str, str | None]: """在一个事务里核对、写轮次、排队、写这一次尝试的第一条事件,提交。交回 (这一轮的 id, 提交之后要取消的挂起旧运行)。""" from app.api.conversations import new_turn, turn_run_id from app.chat import turn as policy @@ -983,8 +1002,16 @@ async def _claim(session: AsyncSession, *, conversation: Any, question: str, dat if retry_of is None: scope = await _scope(session, datasource_ids) row = await new_turn(session, conversation, question) - row.meta = {"v": 1, **({"scope": scope} if scope else {}), "at": now_ms} + clean_depth = depth if depth in ("fast", "deep") else None + row.meta = { + "v": 1, + **({"scope": scope} if scope else {}), + **({"depth": clean_depth} if clean_depth else {}), + "at": now_ms, + } request["scope"] = scope + if clean_depth: + request["depth"] = clean_depth job = ChatTurnJob(id=row.id, conversation_id=conversation.id, status="queued", mode=mode, request=request, principal=principal_snapshot(), actor=actor, started_at=None) session.add(job) @@ -999,6 +1026,10 @@ async def _claim(session: AsyncSession, *, conversation: Any, question: str, dat if job is not None and job.status in runtime.ACTIVE: raise TurnRefused(409, BUSY, TURN_BUSY) meta = dict(row.meta or {}) if isinstance(row.meta, dict) else {} + prev_depth = meta.get("depth") if meta.get("depth") in ("fast", "deep") else None + effective_depth = "deep" if mode == "escalate" else (depth if depth in ("fast", "deep") else prev_depth) + if effective_depth: + request["depth"] = effective_depth scope = await _scope(session, datasource_ids) if datasource_ids is not None else list(meta.get("scope") or []) request["scope"] = scope run_id = turn_run_id(row) @@ -1036,13 +1067,27 @@ async def _claim(session: AsyncSession, *, conversation: Any, question: str, dat archived = record.attempt_record(row, meta, n=len(attempts) + 1, at_ms=int(row.updated_at.timestamp() * 1000) if row.updated_at else now_ms) attempts.append(archived) + switching_mode = prev_depth != effective_depth and effective_depth in ("fast", "deep") if mode == "retry": - reason = record.attempt_reason(archived) - request["base"] = graphful - request["instruction"] = policy.user_retry_instruction(row.question, reason, graphful) + if switching_mode: + # 快速直查 ⇄ 深度分析切换:不沿用异构底图,按原问题重新完整执行目标模式 + request["base"] = False + request["instruction"] = row.question + else: + reason = record.attempt_reason(archived) + request["base"] = graphful + request["instruction"] = policy.user_retry_instruction(row.question, reason, graphful) + elif mode == "escalate": + esc = ((row.review or {}).get("anomaly_escalation") or {}) if isinstance(row.review, dict) else {} + reason = str(esc.get("reason") or record.attempt_reason(archived) or "指标触发异常") + request["base"] = graphful and prev_depth != "fast" + request["instruction"] = str( + esc.get("follow_up_instruction") + or policy.escalation_instruction(row.question, reason, graphful and prev_depth != "fast") + ) usage = record.retire_run(meta.get("usage")) new_meta = {"v": 1, "attempts": attempts or None, "scope": scope or None, "usage": usage or None, - "runId": None, "at": now_ms} + "depth": effective_depth, "runId": None, "at": now_ms} if mode == "run": # 「跑一下」不是重来:这一轮还没有答过,别的照旧 new_meta = {**meta, "runId": None, "at": now_ms, "asked": meta.get("asked")} @@ -1070,6 +1115,7 @@ async def _claim(session: AsyncSession, *, conversation: Any, question: str, dat seq = await turn_log.add(session, turn_id, "turn.attempt", { "mode": mode, "attempts": attempts, "scope": request.get("scope") or [], "usage": usage_now or {}, "started_ms": request.get("started_ms"), + **({"depth": request["depth"]} if request.get("depth") else {}), **({"ended_ms": request["ended_ms"]} if request.get("ended_ms") else {}), **({"max_steps": request["max_steps"]} if request.get("max_steps") else {})}) await session.execute(update(ChatTurnJob).where(ChatTurnJob.id == turn_id).values(attempt_seq=seq) diff --git a/backend/app/chat/launch.py b/backend/app/chat/launch.py index b90f1903..ab8cf952 100644 --- a/backend/app/chat/launch.py +++ b/backend/app/chat/launch.py @@ -61,9 +61,33 @@ async def bind_caliber_tool(session: Any, graph: Any, actor: str | None) -> dict if not await restricted_actor(session, actor): return graph from app.apps.access import usable_calibers + from sqlalchemy import select + from app.db.models import Workflow, WorkflowVersion + from app.ledger.ontology import ACTIVE_LINK_STATUSES, workflow_ontology_index + from app.tools.ontology import ONTOLOGY_NEIGHBORS, SOURCE_HEALTH - if not await usable_calibers(session, actor): + usable = await usable_calibers(session, actor) + if not usable: return graph + + has_ontology_edges = False + for wf_id, ver in usable: + snap = ( + await session.execute( + select(WorkflowVersion.graph).where( + WorkflowVersion.workflow_id == wf_id, + WorkflowVersion.version == int(ver), + ) + ) + ).scalar_one_or_none() + if not isinstance(snap, dict): + wf = await session.get(Workflow, wf_id) + snap = wf.graph if wf is not None and isinstance(wf.graph, dict) else {} + idx = workflow_ontology_index(workflow_id=wf_id, version=int(ver), graph=snap) + if any(e.get("status") in ACTIVE_LINK_STATUSES for e in idx["edges"]): + has_ontology_edges = True + break + nodes = copy.deepcopy(graph["nodes"]) for node in nodes: if not isinstance(node, dict) or str(node.get("type")) != "agent": @@ -74,10 +98,18 @@ async def bind_caliber_tool(session: Any, graph: Any, actor: str | None) -> dict config = here.setdefault("config", {}) if not isinstance(config, dict): continue - tools = [str(t) for t in (node_setting(spec, spec.node_map()[str(node.get("id"))], "tools") or [])] - if CALIBER_QUERY in tools: - continue - config["tools"] = [*tools, CALIBER_QUERY] + spec_node = spec.node_map()[str(node.get("id"))] + tools = [str(t) for t in (node_setting(spec, spec_node, "tools") or [])] + additions = [CALIBER_QUERY] + if has_ontology_edges or bool(node_setting(spec, spec_node, "investigation")): + additions.extend([ONTOLOGY_NEIGHBORS, SOURCE_HEALTH]) + changed = False + for extra_tool in additions: + if extra_tool not in tools: + tools.append(extra_tool) + changed = True + if changed: + config["tools"] = tools return {**graph, "nodes": nodes} diff --git a/backend/app/chat/optimization.py b/backend/app/chat/optimization.py new file mode 100644 index 00000000..7ac35f3a --- /dev/null +++ b/backend/app/chat/optimization.py @@ -0,0 +1,39 @@ +"""Versioned optimizations for newly launched, simple ask-data runs. + +Stored graphs/checkpoints keep their original behavior. No tools or permissions are added. +""" +from __future__ import annotations + +from copy import deepcopy +import re + + +def simple_lookup(question: str) -> bool: + return (0 < len(question.strip()) <= 120 + and bool(re.search(r"多少|查询|查一下|给我|是多少|昨天|今天|前天", question)) + and not re.search(r"分析|原因|为什么|趋势|对比|比较|预测|建议|报告|周报|月报|详细|解释|同比|环比", question)) + + +def prepare(graph: dict, question: str) -> dict: + graph = deepcopy(graph) + nodes = graph.get("nodes") or [] + # Only the standard single-agent lookup chain. Custom analysis/report graphs retain their behavior. + if not simple_lookup(question) or sorted(n.get("type", "") for n in nodes) != ["agent", "input", "output", "report"]: + return graph + by_type = {n["type"]: n for n in nodes} + chain = [by_type[t]["id"] for t in ("input", "agent", "report", "output")] + if {(e.get("source"), e.get("target")) for e in graph.get("edges", [])} != set(zip(chain, chain[1:])): + return graph + if by_type["output"].get("data", {}).get("config", {}).get("contract"): + return graph + for kind in ("agent", "report"): + config = by_type[kind].setdefault("data", {}).setdefault("config", {}) + config["ask_data_optimization"] = 1 + by_type["report"]["data"]["config"]["reuse_answer_from"] = by_type["agent"]["id"] + return graph + + +CONCISE_RULE = """这是一次简短问数。优先使用已授权且已绑定的 caliber_query 或 metric_query;不能绕过工具权限。 +对象、日期与口径明确且已有完整结果时即可结束,不为补充背景反复查询。 +最终答案简短写出结果、对象、时间归属与必要缺口:所有数值必须严格写成带行号的单元格证据引用(例如 [[v:Q1.r0.oee]],必须带 .r0. 这类行号),严禁在引用外手写任何裸数字(包括百分比、行数、差值);查询无返回记录时写「未返回记录」或「暂无数据」,不要写「0 行」。已有证据不足时明确说明,不把不同班次比率简单平均。 +系统会核验这份答案,核验通过后直接作为答复。""" diff --git a/backend/app/chat/turn.py b/backend/app/chat/turn.py index 38021f0d..7c150f2a 100644 --- a/backend/app/chat/turn.py +++ b/backend/app/chat/turn.py @@ -63,6 +63,23 @@ EMPTY_FALLBACK = "这次请直接按输出格式给出操作(每行一个 JSON RETRY_USER_WITH_BASE = ("这个工作流上一次没有给出可用的结果:{reason}。\n\n" "请针对这个原因改它(比如调大最大步数、改正工具参数、换个查询方式)," "改完继续回答原来的问题:{question}") +#: 简单查数命中硬异常信号时,界面提供的一键本体排查提示按钮文案与升级重跑指令(P1) +ESCALATION_BUTTON_LABEL = "指标触发异常,沿本体排查关联数据源" +ESCALATION_WITH_BASE = ( + "上一次回答「{question}」时触发了指标或数据异常:{reason}。\n\n" + "请升级为跨源本体穿透排查工作流(input → agent → report → output):" + "给 agent 绑定 ontology_neighbors、source_health、caliber_query 及分析工具(analysis_comparable、" + "analysis_baseline、analysis_trend、analysis_decompose、analysis_differ、analysis_reconcile、analysis_cochange)," + "按「先调 ontology_neighbors 找已确认关联口径并调 source_health / analysis_reconcile 验数据源健康(发现断更、缺口、" + "量级断崖或单位错位即早停归因数据故障并引用 [[h:H1]] / [[a:A1]])→ 若触发数值契约越界则核查 factor 构成因子与跨库主数据 → " + "若源健康通过则同源 decompose 锁定异常实体切片后沿标准实体桥调 caliber_query + analysis_cochange 检验上游驱动同步异动" + "(严禁把统计共变写成确定因果)」排查异常并给出可核验报告。" +) +ESCALATION_FROM_SCRATCH = ( + "{question}\n\n(指标结果触发异常:{reason}。请沿业务本体排查关联口径与关联数据源健康:搭 input → agent → report → output," + "绑定 ontology_neighbors、source_health、caliber_query 与分析工具,先验源健康与跨源对账,再查构成因子与跨源驱动," + "报告引用 [[h:]] / [[a:]] 证据。)" +) def _blockers(final: Mapping[str, Any]) -> list[str]: @@ -187,13 +204,29 @@ def user_retry_instruction(question: str, reason: str, has_base: bool) -> str: return template.format(question=question, reason=reason) +def escalation_instruction(question: str, reason: str, has_base: bool) -> str: + """指标触发硬异常信号后,沿业务本体排查关联数据源的诊断升级指令(P1)。""" + template = ESCALATION_WITH_BASE if has_base else ESCALATION_FROM_SCRATCH + return template.format(question=question, reason=reason) + + +def escalate_after_review(review: Mapping[str, Any] | None, attempt: int) -> bool: + """异常自动升级模式(anomaly_escalation_mode == 'auto')下最多自动升级 1 轮(attempt == 0)。""" + if not review or attempt != 0: + return False + esc = review.get("anomaly_escalation") + return isinstance(esc, Mapping) and bool(esc.get("available")) and bool(esc.get("auto_escalate")) + + def has_nodes(graph: Any) -> bool: """一张图有没有节点(有才交回去改)。""" return isinstance(graph, Mapping) and bool(graph.get("nodes")) -__all__ = ["EMPTY_FALLBACK", "EMPTY_GENERATION", "MAX_ATTEMPTS", "NEXT_ASKED", "NEXT_DONE", "NEXT_FAIL", "NEXT_READY", +__all__ = ["EMPTY_FALLBACK", "EMPTY_GENERATION", "ESCALATION_BUTTON_LABEL", "ESCALATION_FROM_SCRATCH", + "ESCALATION_WITH_BASE", "MAX_ATTEMPTS", "NEXT_ASKED", "NEXT_DONE", "NEXT_FAIL", "NEXT_READY", "NEXT_REPLY", "NEXT_RETRY", "NEXT_RUN", "NEXT_STEPS", "QUESTION_FIELD", "RETRY_EMPTY", "RETRY_ERRORS", "RETRY_FROM_SCRATCH", "RETRY_USER_WITH_BASE", "RETRY_WITH_BASE", "blocked_reason", - "empty_retry_instruction", "error_reason", "fill_input", "has_nodes", "next_step", "retry_after_review", + "empty_retry_instruction", "error_reason", "escalate_after_review", "escalation_instruction", + "fill_input", "has_nodes", "next_step", "retry_after_review", "retry_instruction", "review_reason", "user_retry_instruction"] diff --git a/backend/app/look/calibers.py b/backend/app/look/calibers.py index c940d649..4c484def 100644 --- a/backend/app/look/calibers.py +++ b/backend/app/look/calibers.py @@ -51,6 +51,16 @@ DETAIL_EXPR_PROMPT = " 指标式:{expression}" DETAIL_DEFINITION_PROMPT = " 定义:{text}" #: 定义说明写进查看结果的上限:口述给人看的边界通常一两句,超出的部分在口径账本里看全文 DEFINITION_MAX = 240 +#: 一跳已确认本体邻居摘要(无关联时不输出,不改变既有口径详情) +DETAIL_ONTOLOGY_PROMPT = ( + " 本体关联指标(已确认关系,异常穿透可调 ontology_neighbors / source_health / caliber_query):{neighbors}" +) +ONTOLOGY_NEIGHBOR_LIMIT = 5 +_ONTOLOGY_KIND_LABELS = { + "factor": "构成因子", + "reconciles_with": "跨源对账", + "upstream_driver": "上游驱动", +} DETAIL_REUSE_PROMPT = (" 复用写法(「看哪些数」这一项的 reuse 照抄,不要改):{reuse}\n" " 这张卡读:{inputs}。实例化时那个库的取数节点就叫这个名字、交出这几列,复用才算得出来") DETAIL_INPUT_PROMPT = "{node}({tool})的列 {columns}" @@ -109,6 +119,7 @@ class CaliberView: reason: str | None #: 指标卡上的定义说明(说明、适用范围、不包含什么),压成一句;没有定义时为空串 definition: str = "" + aliases: tuple[str, ...] = () @property def label(self) -> str: @@ -247,7 +258,9 @@ def metric_options(graph: Mapping[str, Any], card_id: str, *, workflow_id: str, if reason is None: one = caliber_closure.build(graph, workflow_id, version, card_id, metric_ids=[metric_id]) if not one.unresolved: - selectable.append({"metric_id": metric_id, "name": name, **one.summary()}) + semantic = _query_semantic_brief(metric) + selectable.append({"metric_id": metric_id, "name": name, **one.summary(), + **({"query_semantics": semantic} if semantic else {})}) continue reason = problems_text(one.unresolved) unavailable.append({"metric_id": metric_id, "name": name, "reason": reason}) @@ -305,7 +318,9 @@ def views_of(workflow_id: str, workflow_name: str, version: Any) -> list[Caliber level=str(getattr(version, "level", None) or ""), node_id=nid, card=node["title"], caliber=caliber, metric_id=str(metric["id"]), name=str(metric.get("name") or metric["id"]), unit=str(metric.get("unit") or ""), expression=str(metric.get("expression") or ""), inputs=packed, - reason=reason, definition=definition_text(metric.get("definition")))) + reason=reason, definition=definition_text(metric.get("definition")), + aliases=tuple(s for s in [*(metric.get("synonyms") or []), + *((metric.get("semantic") or {}).get("aliases") or [])] if isinstance(s, str)))) return out @@ -345,7 +360,8 @@ class CaliberKind: label = "口径" def __init__(self, items: list[CaliberView], *, picker: Picker | None = None, - options: list[Any] | None = None, query: bool = False) -> None: + options: list[Any] | None = None, query: bool = False, + neighbors: Mapping[tuple[str, int, str, str], list[dict[str, Any]]] | None = None) -> None: self.items = items self.picker = picker #: 问数据里(compose / query 两档):每张卡读好的那一份(入口字段、能算哪些指标、能不能组合),没读时为 None @@ -353,10 +369,12 @@ class CaliberKind: #: 问数据里**普通使用者**那一档(K14):不给 use_caliber(把口径的 SQL 拷进图),只给按口径查询工具取数的写法。 #: use_caliber 能不能用看这个标记(api/copilot_context.composing):options 两档都读,差别只在怎么用 self.query = query + #: 已确认的一跳本体关联指标:{(workflow_id, version, node_id, metric_id): [neighbor_dict, ...]} + self.neighbors: dict[tuple[str, int, str, str], list[dict[str, Any]]] = dict(neighbors or {}) @classmethod async def load(cls, session: Any, *, picker: Picker | None = None, compose: bool = False, - actor: Any = None, query: bool = False) -> CaliberKind: + actor: Any = None, query: bool = False, ontology: bool = True) -> CaliberKind: """读每个工作流**推荐发布版**(Workflow.published_version,K07)里的口径卡。用调用方的会话,开流之前读好。 compose:问数据里(搭建者及以上),另把每张卡的那一版读好、判能不能组合(见模块说明)。 query:问数据里(普通使用者),读同一份数据、但只给按口径查询工具取数的写法(use_caliber 不开)。 @@ -380,7 +398,13 @@ class CaliberKind: if resolved is not None and (permitted is None or (str(wf.id), int(resolved.version)) in permitted): items += views_of(wf.id, wf.name, resolved.row) read = await _options(session, items) if (compose or query) else None - return cls(items, picker=picker, options=read, query=query) + neighbors = await _load_ontology_neighbors( + session, + items, + permitted=permitted, + restricted=bool(query or permitted is not None), + ) if ontology else {} + return cls(items, picker=picker, options=read, query=query, neighbors=neighbors) def option_of(self, item: CaliberView) -> Any | None: if self.options is None: @@ -434,6 +458,16 @@ class CaliberKind: async def pick(self, need: str, sources: list[str] | None) -> tuple[list[tuple[CaliberView, str]], str | None]: pool = self._pool(sources) + from app.ledger.metric_matching import score + + ranked = [(score(need, item.name, item.aliases), item) for item in pool] + hits = [(weight, item) for weight, item in ranked if weight] + if hits: + best = max(weight for weight, _ in hits) + matched = [item for weight, item in hits if weight == best] + if len(matched) <= PICK_LIMIT: + return [(item, "matched") for item in matched], None + return [], "同名口径过多,请指定完整指标名或所属口径" if len(pool) <= PICK_LIMIT: return [(i, "picked") for i in pool], None if self.picker is None: @@ -473,6 +507,11 @@ class CaliberKind: DETAIL_EXPR_PROMPT.format(expression=item.expression)] if item.definition: block.append(DETAIL_DEFINITION_PROMPT.format(text=item.definition)) + item_neighbors = self.neighbors.get((item.workflow_id, item.version, item.node_id, item.metric_id)) + if item_neighbors: + block.append(DETAIL_ONTOLOGY_PROMPT.format( + neighbors=_format_ontology_neighbors(item_neighbors, restricted=self.query) + )) option = self.option_of(item) if option is not None: block += _query_lines(item, option, seen) if self.query else _compose_lines(item, option, seen) @@ -623,9 +662,138 @@ def metric_briefs(entries: Iterable[Mapping[str, Any]]) -> str: out.append(f"{name}({metric_id},要 {'、'.join(need)})" if need else f"{name}({metric_id},不用入口字段)") else: out.append(f"{name}({metric_id}):{m.get('reason')}") + if m.get("query_semantics"): + out[-1] += ";问数定义:" + str(m["query_semantics"]) return ";".join(out) or "无" +def _query_semantic_brief(metric: Mapping[str, Any]) -> str: + """Give the authorized Agent the same published meanings used by the direct router. + + Bound the dictionary size in prompts; an omitted member is not permission to guess it. + The full model remains in the pinned metric definition, not in model-generated SQL. + """ + from pydantic import ValidationError + from app.ledger.semantic import QuerySemantics + + if not isinstance(metric.get("semantic"), Mapping): + return "" + try: + model = QuerySemantics.model_validate(metric["semantic"]) + except ValidationError: + return "定义不完整,先向维护者确认" + if not model.enabled: + return "对象、时间和汇总规则待确认,不要自行推断后查询" + data = model.model_dump(mode="json") + for entity in data["entities"]: + entity["members_truncated"] = len(entity["members"]) > 20 + entity["members"] = entity["members"][:20] + return json.dumps(data, ensure_ascii=False) + ";只按已声明的对象与周期取数;未列出的映射不可猜测" + + +def _format_ontology_neighbors(entries: list[dict[str, Any]], *, restricted: bool = False) -> str: + parts: list[str] = [] + for nb in entries[:ONTOLOGY_NEIGHBOR_LIMIT]: + kind_label = _ONTOLOGY_KIND_LABELS.get(str(nb.get("kind") or ""), str(nb.get("kind") or "")) + extra: list[str] = [kind_label] + if nb.get("role"): + extra.append(f"角色 {nb['role']}") + if nb.get("entity_key"): + extra.append(f"对齐实体 {nb['entity_key']}") + if not restricted and nb.get("sources"): + extra.append("数据源 " + "/".join(str(s) for s in nb["sources"])) + parts.append( + f"{nb['name']}(workflow={nb['workflow_id']},card={nb['card_id']},metric={nb['metric_id']}," + f"{','.join(extra)})" + ) + if len(entries) > ONTOLOGY_NEIGHBOR_LIMIT: + parts.append(f"…另 {len(entries) - ONTOLOGY_NEIGHBOR_LIMIT} 项") + return ";".join(parts) + + +async def _load_ontology_neighbors( + session: Any, + items: list[CaliberView], + *, + permitted: set[tuple[str, int]] | None, + restricted: bool, +) -> dict[tuple[str, int, str, str], list[dict[str, Any]]]: + """加载可见口径指标的一跳已确认本体邻居(过滤 proposed / rejected,并按 permitted 收窄受限用户可见范围)。""" + if not items: + return {} + try: + from app.ledger.ontology import ACTIVE_LINK_STATUSES, build_published_ontology_graph, metric_node_key + + graph = await build_published_ontology_graph(session, include_proposed=False, restricted=restricted) + except Exception: # noqa: BLE001 + return {} + + nodes_by_key = {str(n["key"]): n for n in graph.get("nodes") or [] if isinstance(n, Mapping) and n.get("key")} + item_versions: dict[str, set[int]] = {} + for item in items: + item_versions.setdefault(metric_node_key(item.workflow_id, item.node_id, item.metric_id), set()).add(item.version) + + out: dict[tuple[str, int, str, str], list[dict[str, Any]]] = {} + + def _attach(focal_ref: Mapping[str, Any], peer_ref: Mapping[str, Any], edge: Mapping[str, Any]) -> None: + focal_key = metric_node_key( + str(focal_ref.get("workflow_id") or ""), + str(focal_ref.get("card_id") or ""), + str(focal_ref.get("metric_id") or ""), + ) + versions = item_versions.get(focal_key) + if not versions: + return + peer_key = metric_node_key( + str(peer_ref.get("workflow_id") or ""), + str(peer_ref.get("card_id") or ""), + str(peer_ref.get("metric_id") or ""), + ) + peer = nodes_by_key.get(peer_key) + if peer is None: + return + peer_wf = str(peer["workflow_id"]) + peer_ver = int(peer["version"]) + if permitted is not None and (peer_wf, peer_ver) not in permitted: + return + entry: dict[str, Any] = { + "kind": str(edge.get("kind") or ""), + "role": edge.get("role"), + "entity_key": edge.get("entity_key"), + "workflow_id": peer_wf, + "workflow_name": str(peer.get("workflow_name") or peer_wf), + "version": peer_ver, + "card_id": str(peer["card_id"]), + "metric_id": str(peer["metric_id"]), + "name": str(peer.get("name") or peer["metric_id"]), + } + if not restricted and peer.get("sources"): + entry["sources"] = list(peer["sources"]) + for ver in versions: + slot_key = (str(focal_ref["workflow_id"]), ver, str(focal_ref["card_id"]), str(focal_ref["metric_id"])) + bucket = out.setdefault(slot_key, []) + if not any( + b["workflow_id"] == entry["workflow_id"] + and b["card_id"] == entry["card_id"] + and b["metric_id"] == entry["metric_id"] + and b["kind"] == entry["kind"] + for b in bucket + ): + bucket.append(entry) + + for edge in graph.get("edges") or []: + if not isinstance(edge, Mapping) or edge.get("status") not in ACTIVE_LINK_STATUSES: + continue + src = edge.get("from") + dst = edge.get("to") + if not isinstance(src, Mapping) or not isinstance(dst, Mapping): + continue + _attach(src, dst, edge) + if edge.get("kind") == "reconciles_with": + _attach(dst, src, edge) + return out + + async def verify_reuse(session: Any, ref: dict[str, Any]) -> dict[str, Any]: """蓝图存的时候按库里那一版核对复用的口径卡:已发布且未退役、是源头的口径卡、有这个指标、能复用。交回补上 inputs 的 reuse;不行抛 BpRefused(bp.data_unmapped)。用户在卡片上选的、助手提的都过这一道。""" diff --git a/backend/app/look/service.py b/backend/app/look/service.py index 8ece73fd..665216f5 100644 --- a/backend/app/look/service.py +++ b/backend/app/look/service.py @@ -16,6 +16,7 @@ from __future__ import annotations import logging +import json import time from typing import Any @@ -98,6 +99,7 @@ class LookService: self.texts: list[str] = [] self._seen: set[str] = set() self._n = 0 + self._requests_seen: set[str] = set() @property def default_kind(self) -> str | None: @@ -136,6 +138,10 @@ class LookService: return LookResult(LIMIT_PROMPT.format(limit=budget.limit), None, counted=False) if budget is not None: budget.used += 1 + request_key = json.dumps({"need": need, "targets": parse_targets(line), "sources": _sources(line)}, + ensure_ascii=False, sort_keys=True) + if request_key in self._requests_seen: + return LookResult(REPEAT_PROMPT.format(what="对象"), None, counted=True) self._n += 1 started = time.monotonic() record: dict[str, Any] = {"op": "look", "id": f"L{self._n}", "by": by, "need": need, "status": "ok"} @@ -155,6 +161,8 @@ class LookService: what = "、".join(dict.fromkeys(self.kinds[k.split(":", 1)[0]].label for k in keys)) return LookResult(REPEAT_PROMPT.format(what=what), None, counted=True) self._seen |= keys + if record["status"] == "ok" and keys and not any(o.get("missing") for o in objects): + self._requests_seen.add(request_key) record["elapsed_ms"] = int((time.monotonic() - started) * 1000) record["objects"] = objects text = "\n".join([head, NEED_PROMPT.format(need=need), "", body]) @@ -189,6 +197,7 @@ class LookService: picks[t["kind"]] = None if not targets and self.default_kind: picks[self.default_kind] = None + record["kinds"] = list(dict.fromkeys([*named, *picks])) parts: list[str] = [] objects: list[dict[str, Any]] = [] keys: set[str] = set() diff --git a/backend/app/look/tables.py b/backend/app/look/tables.py index cabfb974..5b9dc7e2 100644 --- a/backend/app/look/tables.py +++ b/backend/app/look/tables.py @@ -66,6 +66,10 @@ INDEX_SCOPED_PROMPT = ("数据源「{source}」(共 {total} 张表,探查范 "按需加入):") PICK_WHAT_PROMPT = "数据表" PICK_LINE_PROMPT = "每行一张表:表名|中文名|粒度" +ENTITY_BRIDGE_HEAD_PROMPT = ( + " 跨源标准实体桥(已确认绑定;跨源穿透优先走 caliber_query,搭建者对齐粒度后可辅以 1 跳 db_query__):" +) +ENTITY_BRIDGE_LIMIT = 6 @dataclass @@ -80,6 +84,8 @@ class SourcePlan: facts: dict[str, dict[str, Any]] = field(default_factory=dict) #: 对象索引里探查范围外的对象(source_objects.outside_objects):检索、点名时用,点到了按需加入 outside: list[Any] = field(default_factory=list) + #: 桥接到其他数据源的已确认标准业务实体(仅非受限搭建者/管理员填充) + entity_bridges: list[dict[str, Any]] = field(default_factory=list) _graph: dict[str, list[JoinEdge]] | None = None _search: Any = None _outside_keys: dict[str, Any] | None = None @@ -237,7 +243,7 @@ class TableKind: @classmethod async def load(cls, sources: list[Any], *, graph: Mapping[str, Any] | None = None, picker: Picker | None = None, catalog_view: Any = None, - trail: Mapping[str, Any] | None = None) -> TableKind: + trail: Mapping[str, Any] | None = None, ontology: bool = True) -> TableKind: """读各源的数据目录、剖析事实、探查范围外的对象清单。graph 是现有工作流(改图时的原图、追问时上一轮的图),概览里 列出它查过的表。trail 是按需加入的留痕(谁、哪一轮对话):不给时谁取这次请求的身份。 @@ -249,12 +255,12 @@ class TableKind: seeds = graph_tables(graph, sources) plans = [SourcePlan(source=s, entries=await read(view, s) if introspect.table_names(s) else {}, seeds=seeds.get(s.name, [])) for s in sources] - await _load_extras(plans) trail = dict(trail or {}) if "actor" not in trail: from app.api.deps import current_principal trail["actor"] = current_principal().username + await _load_extras(plans, actor=trail.get("actor"), ontology=ontology) return cls(plans, picker=picker, trail=trail) def begin(self, *, need: str, ref: str) -> None: @@ -582,6 +588,7 @@ class TableKind: lines += [f" {x}" for x in block[1:]] lines += schema_view.join_lines(p.source, p.graph(), tables, indent=" ") lines += schema_view.route_lines(p.source, routes, indent=" ") + lines += _entity_bridge_lines(p, tables) if self._added.get(i): lines.append(" " + ADDED_PROMPT.format(tables="、".join(p.qualified(t) for t in self._added[i]))) if p.unexplored: @@ -655,15 +662,51 @@ class TableKind: return out -async def _load_extras(plans: list[SourcePlan]) -> None: - """各源的剖析事实、探查范围外的对象清单:一个短会话读完。读不到就当没有(少一节剖析事实、少几个可按需加入的名字), - 不挡生成。上传表格、记录表没有对象索引;探查范围以内就是全部的源(没有范围外的对象)不读清单。""" +def _entity_bridge_lines(p: SourcePlan, tables: list[str]) -> list[str]: + """当前源查看的几张表上,已确认的标准业务实体桥接到哪些其他数据源与物理表列(仅非受限角色可见)。""" + if not p.entity_bridges or not tables: + return [] + table_keys = {name_key(t) for t in tables} | {name_key(t.rsplit(".", 1)[-1]) for t in tables} + matched_lines: list[str] = [] + for bridge in p.entity_bridges: + local = [ + b for b in bridge.get("local_bindings") or [] + if name_key(str(b.get("table_name") or "")) in table_keys + or name_key(str(b.get("table_name") or "").rsplit(".", 1)[-1]) in table_keys + ] + peers = list(bridge.get("peer_bindings") or []) + if not local or not peers: + continue + local_desc = "、".join(f"{b['table_name']}.{b['column_name']}" for b in local[:3]) + peer_desc = "、".join( + f"{b['source_name']}:{b['table_name']}.{b['column_name']}" for b in peers[:4] + ) + matched_lines.append( + f" · {bridge['label']}({bridge['key']}):本源 {local_desc} ↔ 关联源 {peer_desc}" + ) + if len(matched_lines) >= ENTITY_BRIDGE_LIMIT: + break + return [ENTITY_BRIDGE_HEAD_PROMPT, *matched_lines] if matched_lines else [] + + +async def _load_extras(plans: list[SourcePlan], *, actor: Any = None, ontology: bool = True) -> None: + """各源的剖析事实、探查范围外的对象清单与跨源标准实体桥:一个短会话读完。读不到就当没有(少一节剖析事实、少几个可按需加入的名字), + 不挡生成。上传表格、记录表没有对象索引;探查范围以内就是全部的源(没有范围外的对象)不读清单;普通受限使用者不加载物理表桥。""" + from app.auth.chat_policy import effective_actor, restricted_actor from app.data import catalog_profile_jobs, source_objects + from app.data.entities import entities_bridging_sources, list_entities from app.db.base import SessionLocal try: async with SessionLocal() as session: + is_restricted = await restricted_actor(session, effective_actor(actor)) + entity_rows = [] if (is_restricted or not ontology) else await list_entities(session) for p in plans: + if entity_rows and p.tables: + p.entity_bridges = [ + b for b in entities_bridging_sources(entity_rows, source_name=p.name) + if b.get("peer_bindings") + ] source_id = getattr(p.source, "id", None) if not source_id: continue diff --git a/backend/tests/test_ask_data_optimization.py b/backend/tests/test_ask_data_optimization.py new file mode 100644 index 00000000..802493a3 --- /dev/null +++ b/backend/tests/test_ask_data_optimization.py @@ -0,0 +1,203 @@ +"""Legacy ask-data optimization through real query tools, evidence sealing and migration APIs.""" +from __future__ import annotations + +import copy + +import pytest +from langchain_core.messages import AIMessage + +from app.chat.optimization import prepare +from app.db.base import SessionLocal +from app.db.models import CaliberDraft, DataSource, Document, Workflow +from app.engine.guards import call_key +from app.engine.runner import run_manager, verify_manifest +from app.ledger.migration import audit +from tests import ledger_samples as S +from tests.test_semantic_pipeline import ( # noqa: F401 + SOURCE, client, cleanup_own_rows, engine_up, no_model, oee_asset, oee_graph, _ops, +) +from tests.test_report_node import events, report_of + + +def ask_graph(): + return S.chain(S.node("start", "input"), + S.node("work", "agent", prompt="昨天1050的OEE是多少", tools=[S.tool()], approval="never"), + S.node("write", "report", instructions="简短回答查询问题并引用证据"), + S.node("out", "output", fields=[{"name": "答案", "value": "{{ nodes.write.text }}"}])) + + +def test_only_simple_lookup_graphs_are_opted_in_without_mutating_saved_graph(): + graph = ask_graph() + before = copy.deepcopy(graph) + optimized = prepare(graph, "昨天1050的OEE是多少") + assert optimized["nodes"][1]["data"]["config"]["ask_data_optimization"] == 1 + assert optimized["nodes"][2]["data"]["config"]["reuse_answer_from"] == "work" + assert graph == before + assert prepare(graph, "分析昨天1050的OEE为什么下降") == graph + graph["nodes"][-1]["data"]["config"]["contract"] = {"required_metrics": ["oee"]} + assert prepare(graph, "昨天1050的OEE是多少") == graph + + +def test_normalized_calls_preserve_literals_sources_and_parameters(): + key = lambda sql, **args: call_key("db_query__shop", {"sql": sql, **args}, canonical=True) + assert key("SELECT x FROM t") == key("SELECT\nx FROM\nt") + assert key("SELECT 'a b'") != key("SELECT 'a b'") + assert key('SELECT "a b" FROM t') != key('SELECT "a b" FROM t') + assert key("SELECT x FROM t -- a\nWHERE id=1") != key("SELECT x FROM t WHERE id=1") + assert key("SELECT x FROM t", limit=1) != key("SELECT x FROM t", limit=100) + assert call_key("db_query__shop", {"sql": "SELECT x"}) != call_key("db_query__shop", {"sql": "SELECT x"}) + assert call_key("db_schema__shop", {"table": ["a", "b"]}, canonical=True) == call_key( + "db_schema__shop", {"table": "b,a"}, canonical=True) + assert call_key("db_schema__shop", {"table": ["a"]}, canonical=True) != call_key( + "db_schema__other", {"table": ["a"]}, canonical=True) + + +@pytest.mark.parametrize("mode, expected_calls", [("clean", 0), ("bare", 1), ("wrong_ref", 1), ("formal", 1)]) +async def test_agent_answer_reuse_still_checks_evidence_and_seals(oee_asset, monkeypatch, mode, expected_calls): + from app.providers.mock_model import MockChatModel + + sql = "SELECT SUM(oee * hours) / SUM(hours) AS oee FROM shifts WHERE oee IS NOT NULL AND plant='1050' AND production_day='2026-11-09'" + calls = {"agent": 0, "report": 0} + + def decide(self, messages): + if not self.tools: + calls["report"] += 1 + return AIMessage(content="OEE 为 [[v:Q1.r0.oee]]%。[[see:Q1]]") + calls["agent"] += 1 + step = calls["agent"] + if step <= 2: + return AIMessage(content="", tool_calls=[{"name": S.tool(), "id": f"call_{step}", + "args": {"sql": sql if step == 1 else sql.replace(" FROM ", "\n FROM ")}}]) + return AIMessage(content={"bare": "OEE 为 999%。", "wrong_ref": "OEE 为 [[v:Q99.r0.oee]]%。"}.get( + mode, "OEE 为 [[v:Q1.r0.oee]]%。[[see:Q1]]")) + + monkeypatch.setattr(MockChatModel, "_decide", decide) + run = await run_manager.start(graph=prepare(ask_graph(), "昨天1050的OEE是多少"), input_payload={}, + run_class="formal" if mode == "formal" else "exploratory") + row = await S.wait(run.id) + assert row.status == "succeeded", row.error + assert calls == {"agent": 3, "report": expected_calls} + tool_ends = [e for e in await events(run.id) if e.type == "tool.end"] + assert len(tool_ends) == 1, [e.type for e in await events(run.id)] + checked, doc = await report_of(run.id) + assert checked["ok"] and "40" in doc["markdown"] and "999" not in doc["markdown"] + assert (await verify_manifest(run.id))["ok"] + assert bool([e for e in await events(run.id) if e.data.get("code") == "report_answer_reused"]) == (mode == "clean") + + +def test_migration_reports_grain_source_and_boundary_without_rewriting(): + graph = oee_graph() + graph["nodes"][1]["data"]["config"]["args"]["sql"] = "SELECT oee FROM shifts" + metric = graph["nodes"][2]["data"]["config"]["metrics"][0] + metric.pop("semantic") + before = copy.deepcopy(graph) + result = audit(graph, workflow_id="legacy", version=3, sources=set()) + codes = {f["code"] for f in result["metrics"][0]["findings"]} + assert {"semantic_missing", "source_missing", "scalar_unproven"} <= codes + assert not result["runtime_verified"] and graph == before + + +async def test_migration_draft_is_independent_idempotent_and_keeps_source(oee_asset, client): + async with SessionLocal() as session: + workflow = await session.get(Workflow, oee_asset["workflow_id"]) + old_graph, old_revision, old_published = copy.deepcopy(workflow.graph), workflow.version, workflow.published_version + doc = Document(title="指标公式总表.md", source="migration-test", content=SOURCE.read_text(), status="ready") + session.add(doc) + await session.flush() + draft = CaliberDraft(title="迁移测试", status="questions_open", workflow_id=workflow.id, + origin={"documents": [doc.id], "fixed_filters": "仅测试范围"}, payload={}) + session.add(draft) + await session.commit() + draft_id = draft.id + check = await client.get(f"/api/ledger/drafts/{draft_id}/migration") + assert check.status_code == 200, check.text + assert check.json()["metrics_total"] == 1 and check.json()["can_rebuild"] + response = await client.post(f"/api/ledger/drafts/{draft_id}/migration", json={"expected_revision": old_revision}) + assert response.status_code == 201, response.text + again = await client.post(f"/api/ledger/drafts/{draft_id}/migration", json={"expected_revision": old_revision}) + assert response.json() == again.json() + fresh = (await client.get(f"/api/ledger/drafts/{response.json()['draft_id']}" )).json() + assert fresh["workflow_id"] is None and fresh["definition_count"] == 48 + assert fresh["origin"]["fixed_filters"] == "仅测试范围" + async with SessionLocal() as session: + wf = await session.get(Workflow, oee_asset["workflow_id"]) + assert wf.graph == old_graph and wf.version == old_revision and wf.published_version == old_published + stale = await client.post(f"/api/ledger/drafts/{draft_id}/migration", json={"expected_revision": old_revision + 1}) + assert stale.status_code == 409 + + +async def test_explicit_source_scope_cannot_be_bypassed_by_fast_route(oee_asset): + from app.api.copilot import GenerateIn, _auto_route_ops + from tests.fixtures.sources import drop_source + + async with SessionLocal() as session: + source = DataSource(name="only_this_scope", kind="sqlite", database=":memory:") + session.add(source) + await session.commit() + source_id = source.id + try: + # A caliber from another database is not a candidate for this scoped question. + # Return control to scoped exploration, rather than executing it or hijacking the turn with clarification. + ops = await _auto_route_ops(GenerateIn(instruction="昨天1050的OEE是多少", intent="answer", + datasource_ids=[source_id])) + assert ops is None + finally: + await drop_source(source_id) + + +async def test_migration_requires_builder_even_for_read_only_audit(client): + from tests.fakes import auth_env + + await auth_env.reset() + admin = await auth_env.turn_on_local() + await auth_env.make_user("migration-user", role="user") + user = await auth_env.login("migration-user") + try: + response = await user.get("/api/ledger/drafts/absent/migration") + write = await user.post("/api/ledger/drafts/absent/migration", json={"expected_revision": 1}) + assert response.status_code == write.status_code == 403 + finally: + await user.aclose() + await admin.aclose() + await auth_env.reset() + + +async def test_matching_and_repeated_look_do_not_call_picker_again(): + from tests.test_look_caliber_definition import _view + from app.look.calibers import CaliberKind + from app.look.service import LookService + + class Picker: + async def pick(self, **kwargs): + raise AssertionError("known metric retrieval must not need a model") + + kind = CaliberKind([_view(name=f"无关指标{i}", metric_id=f"x{i}") for i in range(50)] + [ + _view(name="装配线 OEE", metric_id="assembly"), _view(name="发泡线 OEE", metric_id="foam")], picker=Picker()) + result, reason = await kind.pick("昨天1050的OEE是多少", None) + assert reason is None and {v.metric_id for v, _ in result} == {"assembly", "foam"} + service = LookService([kind]) + request = {"need": "昨天1050的OEE是多少", "targets": [{"kind": "caliber"}]} + first = await service.look(request) + assert first.record["kinds"] == ["caliber"] + + async def no_more(*args, **kwargs): + raise AssertionError("duplicate look must short circuit before pick/detail") + kind.pick = no_more + second = await service.look(request) + assert second.record is None + + +async def test_analysis_request_is_not_blocked_by_disabled_or_ambiguous_semantics(monkeypatch): + from app.ledger import nlchange + + async def cards(_): + return [{"workflow_id": "one", "version": 1, "workflow_name": "OEE口径", "caliber": "OEE", + "card_title": "OEE", "card_id": "card", "metrics": [ + {"id": "m1", "name": "装配线 OEE", "semantic": {"enabled": False, "aliases": ["OEE"]}}, + {"id": "m2", "name": "发泡线 OEE", "semantic": {"enabled": False, "aliases": ["OEE"]}}]}] + monkeypatch.setattr(nlchange, "_auto_cards", cards) + for question in ("分析昨天1050的OEE", "昨天1050的OEE为什么下降", "查一下昨天1050的OEE,解释原因"): + assert await nlchange.auto_route(None, question=question) is None + # Analysis does not grant access to an otherwise inaccessible matched asset. + refused = await nlchange.auto_route(None, question="分析昨天1050的OEE", allowed=set()) + assert refused.mode == nlchange.ROUTE_REFUSED diff --git a/backend/tests/test_auto_route_source_scope.py b/backend/tests/test_auto_route_source_scope.py new file mode 100644 index 00000000..cac954dd --- /dev/null +++ b/backend/tests/test_auto_route_source_scope.py @@ -0,0 +1,81 @@ +"""Clarifications must respect database scope before stealing an exploratory turn.""" +import pytest + +from app.api import copilot +from app.db.base import SessionLocal +from app.ledger import nlchange + + +async def test_legacy_clarification_ignores_other_or_disabled_sources(monkeypatch): + async def cards(session): + return [{'workflow_id': 'legacy', 'version': 1, 'card_id': 'card', 'workflow_name': '历史口径', + 'caliber': '旧定义', 'card_title': '指标卡', 'metric_source_tools': {'m1': {'db_query__old_database'}}, + 'metrics': [{'id': 'm1', 'name': '遗留销售额', 'expression': "cell(nodes.fetch, 0, 'n')"}]}] + monkeypatch.setattr(nlchange, '_auto_cards', cards) + async with SessionLocal() as session: + assert await nlchange.auto_route(session, question='昨天1050的遗留销售额', + source_tools={'db_query__selected_database'}) is None + assert await nlchange.auto_route(session, question='昨天1050的遗留销售额', source_tools=set()) is None + matched = await nlchange.auto_route(session, question='昨天1050的遗留销售额', + source_tools={'db_query__old_database'}) + assert matched.mode == nlchange.ROUTE_CLARIFY + + +async def test_missing_explicit_source_is_rejected_before_any_clarification(monkeypatch): + from app.api.coded import CodedHTTPException + + async def should_not_route(*args, **kwargs): + raise AssertionError('must validate source scope before routing') + monkeypatch.setattr(nlchange, 'auto_route', should_not_route) + with pytest.raises(CodedHTTPException) as refused: + await copilot._auto_route_ops(copilot.GenerateIn( + instruction='昨天1050的遗留销售额', datasource_ids=['missing-route-regression-source'])) + assert refused.value.status_code == 400 + assert refused.value.code == 'datasource_scope_empty' + + +async def test_multisource_graph_routes_only_selected_metric_dependencies(): + from sqlalchemy import delete + from app.db.models import Workflow, WorkflowVersion + from app.ledger.draftplan import build_graph + from tests import binding_samples as B + + graph = build_graph([ + {'sql': 'SELECT 1 AS n', 'entry_fields': [], 'metrics': [ + {'id': 'a', 'name': '单源路由指标甲', 'expression': "cell(nodes.fetch, 0, 'n')"}]}, + {'sql': 'SELECT 2 AS n', 'entry_fields': [], 'metrics': [ + {'id': 'b', 'name': '单源路由指标乙', 'expression': "cell(nodes.fetch, 0, 'n')"}]}, + ], name='多源图', datasource='source_a') + second = next(n for n in graph['nodes'] if n['id'] == 'fetch_2') + second['data']['config']['tool'] = 'db_query__source_b' + # Another card in the same workflow cannot pollute the target card's source scope either. + graph['nodes'].append({'id': 'other_card', 'type': 'metrics', 'data': {'config': {'metrics': [ + {'id': 'c', 'name': '另卡路由指标丙', 'expression': "cell(nodes.fetch_2, 0, 'n')"}]}}}) + next(n for n in graph['nodes'] if n['id'] == 'card')['data']['config']['metrics'].append( + {'id': 'constant', 'name': '常量路由指标丁', 'expression': '1'}) + workflow_id = await B.publish(graph, name='多源选择回归') + try: + async with SessionLocal() as session: + first = await nlchange.auto_route(session, question='单源路由指标甲是多少', + source_tools={'db_query__source_a'}) + assert first.mode == nlchange.ROUTE_EXECUTE + assert first.request['metric_ids'] == ['a'] + assert await nlchange.auto_route(session, question='单源路由指标乙是多少', + source_tools={'db_query__source_a'}) is None + assert await nlchange.auto_route(session, question='另卡路由指标丙是多少', + source_tools={'db_query__source_a'}) is None + second = await nlchange.auto_route(session, question='单源路由指标乙是多少', + source_tools={'db_query__source_b'}) + assert second.mode == nlchange.ROUTE_EXECUTE and second.request['metric_ids'] == ['b'] + clarified = await nlchange.auto_route(session, question='昨天1050的单源路由指标甲', + source_tools={'db_query__source_a'}) + assert clarified.mode == nlchange.ROUTE_CLARIFY + assert await nlchange.auto_route(session, question='昨天1050的常量路由指标丁', + source_tools={'db_query__source_a'}) is None + global_constant = await nlchange.auto_route(session, question='昨天1050的常量路由指标丁') + assert global_constant.mode == nlchange.ROUTE_CLARIFY + finally: + async with SessionLocal() as session: + await session.execute(delete(WorkflowVersion).where(WorkflowVersion.workflow_id == workflow_id)) + await session.execute(delete(Workflow).where(Workflow.id == workflow_id)) + await session.commit() diff --git a/backend/tests/test_chat_turns.py b/backend/tests/test_chat_turns.py index e41c6ee4..2cd85023 100644 --- a/backend/tests/test_chat_turns.py +++ b/backend/tests/test_chat_turns.py @@ -283,7 +283,8 @@ async def test_stop_while_building(client, monkeypatch, source): gate = asyncio.Event() es.use_copilot(monkeypatch, Gated(source["name"], gate)) conversation_id = await _conversation(client) - turn_id = await _ask(client, conversation_id) + # This exercises the exploratory builder, not globally published semantic definitions. + turn_id = await _ask(client, conversation_id, datasource_ids=[source["id"]]) await _stage(turn_id, "build") r = await client.post(f"/api/chat/turns/{turn_id}/cancel") assert r.status_code == 200, r.text diff --git a/backend/tests/test_chat_turns_races.py b/backend/tests/test_chat_turns_races.py index 0ded95cb..9107eea4 100644 --- a/backend/tests/test_chat_turns_races.py +++ b/backend/tests/test_chat_turns_races.py @@ -172,7 +172,7 @@ async def test_the_job_manager_does_not_start_a_turn_twice(client, monkeypatch, gate = asyncio.Event() es.use_copilot(monkeypatch, Counting(source["name"], gate=gate, mode="reply")) conversation_id = await _conversation(client) - turn_id = await _ask(client, conversation_id) + turn_id = await _ask(client, conversation_id, datasource_ids=[source["id"]]) await _stage(turn_id, "build") first = chat_job.manager._runs[turn_id] assert chat_job.manager.start(turn_id) is False, "还在跑的同一轮不起第二个" diff --git a/backend/tests/test_chat_user_caliber.py b/backend/tests/test_chat_user_caliber.py index 8938d7fc..ddc3ccfd 100644 --- a/backend/tests/test_chat_user_caliber.py +++ b/backend/tests/test_chat_user_caliber.py @@ -5,7 +5,7 @@ look → 建图 / 固定执行 → 收尾写库),不只测 helper: 1. **授权 look**:使用者这一轮的 system 里列着他有授权的口径(入口字段 + 按口径查询工具取数的写法),没有授权的口径一个字 都不出现;他这一轮也**没有** use_caliber 那段协议(把口径的取数 SQL 拷进图里那条路只给搭建者及以上); -2. **非精确问法**(「上个月<指标>是多少」):模型按查看结果搭「入口 → agent(绑 caliber_query)→ 出口」,运行真的调这个 +2. **分析问法**(「分析<指标>在指定月份的数值」):模型按查看结果搭「入口 → agent(绑 caliber_query)→ 出口」,运行真的调这个 工具取到数、交回的值写进答案——不是只能查底表; 3. **next 与运行归属**:命中固定执行(「<指标> 2026年9月是多少」)时 final.next = done(不是 ready),driver 把那次运行 收进这一轮(turn.run_id / meta.runId / run 事件)、页面据此重载查看,答案用 final 那句白话,整轮零模型、不再整轮复核; @@ -46,8 +46,8 @@ CARD = "card" NAME = "集成口径专用净额甲" #: 合成库的窗口:2026-09-01(含)≤ paid_at < 2026-10-01(不含) WINDOW_INPUTS = {"start": "2026-09-01", "end": "2026-10-01"} -#: 非精确问法(remainder 拆出来是「上个月」,和指标名不等:走模型那条路) -QUESTION_FUZZY = f"上个月{NAME}是多少" +#: 分析问法:继续由已授权的 Agent 选用口径;旧口径的相对日期问数另走迁移澄清。 +QUESTION_FUZZY = f"分析{NAME}在2026年9月的数值" #: 精确问法(拆出来正是指标名:走固定执行那条路) QUESTION_EXACT = f"{NAME} 2026年9月是多少" @@ -290,8 +290,8 @@ async def world(tmp_path, monkeypatch): # ========================================================================== -async def test_a_vague_question_uses_the_authorized_caliber_through_the_tool(world, monkeypatch): - """「上个月<指标>是多少」不精确:助手看得见**有授权的**口径与参数,按它搭 agent 调 caliber_query 取数。""" +async def test_an_analysis_question_uses_the_authorized_caliber_through_the_tool(world, monkeypatch): + """分析问题:助手看得见**有授权的**口径与参数,按它搭 agent 调 caliber_query 取数。""" asset = world["asset"] # 另一份口径没授权给它:一个字都不该出现在这一轮里(清单按资产授权收窄) hidden = await _unauthorized_asset(world) diff --git a/backend/tests/test_direct_ask_and_metrics.py b/backend/tests/test_direct_ask_and_metrics.py new file mode 100644 index 00000000..ba6fc09b --- /dev/null +++ b/backend/tests/test_direct_ask_and_metrics.py @@ -0,0 +1,689 @@ +"""快速直查问数引擎(M3)、毫秒级确定性语义预命中(M2)与独立语义指标库 + metric_query 工具(M1)端到端测试。""" +from __future__ import annotations + +import json +import sqlite3 +import time +import uuid +from pathlib import Path +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient +from langchain_core.messages import AIMessage, ToolMessage +from sqlalchemy import delete, select + +from app.capabilities.registry import is_platform_query, snapshot_owned +from app.chat import job as chat_job +from app.chat import log as turn_log +from app.chat.grounding import ground_question +from app.data import catalog, catalog_assistant +from app.data.catalog import make_item +from app.data.engine import CATALOG_PROFILE_OPTION, MASK_COLUMNS_OPTION +from app.db.base import SessionLocal +from app.db.models import Artifact, ConversationTurn, Document, Run, RunEvent +from app.db.models_chat import ChatTurnJob +from app.db.models_metrics import SemanticMetric +from app.db.models_ontology import CanonicalEntity +from app.engine.evidence import iter_segments +from app.engine.runner import run_manager +from app.main import app +from app.providers import mock_model +from app.tools.metrics import METRIC_QUERY +from tests import eval_samples as es +from tests.fixtures.sources import drop_source, sqlite_source + + +@pytest.fixture(autouse=True) +async def _engine_lifecycle(): + await run_manager.setup() + yield + await chat_job.shutdown() + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(SemanticMetric)) + await session.execute(delete(CanonicalEntity).where(CanonicalEntity.key.like("zy_test_%"))) + await session.execute(delete(Document).where(Document.source == "test_metric_formula.md")) + await session.commit() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +async def _create_zhangyuan_fixture(tmp_path: Path) -> dict[str, str]: + db_path = tmp_path / f"zhangyuan_{uuid.uuid4().hex[:6]}.db" + conn = sqlite3.connect(db_path) + try: + conn.executescript( + """ + CREATE TABLE footfall_daily ( + id INTEGER PRIMARY KEY, + stat_date TEXT NOT NULL, + zone_code TEXT NOT NULL, + total_sys INTEGER NOT NULL, + crowd_density INTEGER NOT NULL, + secret_phone TEXT, + status INTEGER NOT NULL DEFAULT 1 + ); + INSERT INTO footfall_daily (stat_date, zone_code, total_sys, crowd_density, secret_phone, status) VALUES + ('2026-11-09', 'Z_WEST_04', 1200, 85, '13800001111', 1), + ('2026-11-09', 'Z_EAST_01', 800, 60, '13800002222', 1), + ('2026-11-10', 'Z_WEST_04', 1500, 92, '13800003333', 1), + ('2026-11-10', 'Z_EAST_01', 900, 65, '13800004444', 1), + ('2026-11-10', 'Z_WEST_04', 9999, 99, '13800005555', 0); + """ + ) + conn.commit() + finally: + conn.close() + + src_name = f"zhangyuan_{uuid.uuid4().hex[:6]}" + sid = await sqlite_source( + src_name, + db_path, + options={ + CATALOG_PROFILE_OPTION: {"enabled": True}, + MASK_COLUMNS_OPTION: "secret_phone", + }, + schema=True, + ) + + notes = { + "label": make_item("园区日度客流汇总表", "human"), + "grain": make_item("每日期每区域一行", "human"), + "business_date": make_item({"column": "stat_date", "rule": "按园区营业归属日统计(T+1 更新)"}, "human"), + "valid_filter": make_item("status = 1", "human"), + "columns": { + "total_sys": {"label": make_item("系统去重客流", "human"), "unit": make_item("人次", "human"), "measure": make_item("flow", "human")}, + "crowd_density": {"label": make_item("瞬时在园峰值密度", "human"), "measure": make_item("stock", "human")}, + "zone_code": {"label": make_item("区域编码", "human")}, + "secret_phone": {"label": make_item("敏感手机号绝密备注", "human")}, + }, + } + async with SessionLocal() as session: + await catalog.write_entry(session, sid, "footfall_daily", notes, if_version=0, actor="tester") + ent = CanonicalEntity( + key="zy_test_zone", + label="园区区域", + description="张园标准商业区域实体", + bindings=[ + { + "id": "b1", + "source_id": sid, + "source_name": src_name, + "table_name": "footfall_daily", + "column_name": "zone_code", + "status": "confirmed", + "confidence": 1.0, + } + ], + members=[ + { + "id": "m1", + "value": "WEST_04", + "label": "西区四号楼", + "aliases": ["W4", "四号楼"], + "source_codes": {src_name: "Z_WEST_04"}, + }, + { + "id": "m2", + "value": "EAST_01", + "label": "东区一号楼", + "aliases": ["E1"], + "source_codes": {src_name: "Z_EAST_01"}, + }, + ], + ) + session.add(ent) + await session.commit() + + return {"id": sid, "name": src_name, "entity_key": "zy_test_zone"} + + +async def test_semantic_metric_crud_and_sql_guardrails(client: AsyncClient, tmp_path: Path): + fx = await _create_zhangyuan_fixture(tmp_path) + try: + # 1. SQL 护栏校验:拦截分号多语句、嵌套子查询、不存在的物理列、以及敏感遮罩列 + for bad_expr, note in [ + ("SUM(total_sys); DROP TABLE footfall_daily", "分号多语句"), + ("(SELECT SUM(total_sys) FROM footfall_daily)", "嵌套子查询"), + ("SUM(non_existent_col)", "不存在列"), + ("COUNT(secret_phone)", "敏感遮罩列"), + ]: + r = await client.post( + "/api/semantic-metrics", + json={ + "key": "zy_bad_metric", + "name": "非法指标", + "source_id": fx["id"], + "table_name": "footfall_daily", + "sql_expression": bad_expr, + }, + ) + assert r.status_code == 422, f"{note} 未被拦截: {r.text}" + + # 2. 正常创建指标卡片,即存即生效 + r = await client.post( + "/api/semantic-metrics", + json={ + "key": "zy_daily_footfall_sys", + "name": "张园日客流(系统去重)", + "aliases": ["客流", "总客流"], + "unit": "人次", + "description": "按系统去重统计有效客流", + "source_id": fx["id"], + "table_name": "footfall_daily", + "sql_expression": "SUM(total_sys)", + "date_column": "stat_date", + "filter_sql": "status = 1", + "dimensions": [ + {"key": "zone", "label": "园区区域", "column": "zone_code", "entity_key": fx["entity_key"]} + ], + }, + ) + assert r.status_code == 201, r.text + created = r.json()["metric"] + metric_id = created["id"] + assert created["version"] == 1 and created["aggregation_type"] == "sum" + + # 3. 列表查询与乐观锁版本冲突保护 + listed = (await client.get("/api/semantic-metrics", params={"q": "客流"})).json() + assert listed["total"] == 1 and listed["items"][0]["key"] == "zy_daily_footfall_sys" + + upd = await client.put( + f"/api/semantic-metrics/{metric_id}", + json={"unit": "人", "expected_version": 1}, + ) + assert upd.status_code == 200 and upd.json()["metric"]["version"] == 2 + + stale = await client.put( + f"/api/semantic-metrics/{metric_id}", + json={"unit": "人次", "expected_version": 1}, + ) + assert stale.status_code == 409, stale.text + + # 4. 删除 + deleted = await client.delete(f"/api/semantic-metrics/{metric_id}") + assert deleted.status_code == 200 and deleted.json()["ok"] is True + assert (await client.get(f"/api/semantic-metrics/{metric_id}")).status_code == 404 + finally: + await drop_source(fx["id"]) + + +async def test_metric_preview_entity_translation_and_latest_date_probe(client: AsyncClient, tmp_path: Path): + fx = await _create_zhangyuan_fixture(tmp_path) + try: + r = await client.post( + "/api/semantic-metrics", + json={ + "key": "zy_footfall", + "name": "张园客流", + "aliases": ["客流量"], + "unit": "人次", + "source_id": fx["id"], + "table_name": "footfall_daily", + "sql_expression": "SUM(total_sys)", + "date_column": "stat_date", + "filter_sql": "status = 1", + "dimensions": [ + {"key": "zone", "label": "园区区域", "column": "zone_code", "entity_key": fx["entity_key"]} + ], + }, + ) + assert r.status_code == 201, r.text + metric_id = r.json()["metric"]["id"] + + # 1. 按标准实体中文别名「四号楼」筛选 + 按日趋势分组:自动翻译为底层编码 Z_WEST_04 并过滤掉 status=0 脏数据 + prev = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": metric_id, + "date_from": "2026-11-09", + "date_to": "2026-11-10", + "group_by_date": True, + "filters": {"zone": "四号楼"}, + }, + ) + assert prev.status_code == 200, prev.text + body = prev.json() + assert body["row_count"] == 2 + assert [row[1] for row in body["rows"]] == [1200, 1500] + assert body["entity_alignments"] and body["entity_alignments"][0]["translated"] == ["Z_WEST_04"] + + # 2. T+1 场景:查尚未入库的日期 2026-11-12 时,一次返回 latest_available_date = '2026-11-10' + empty_prev = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": metric_id, + "date_from": "2026-11-12", + "date_to": "2026-11-12", + }, + ) + assert empty_prev.status_code == 200, empty_prev.text + eb = empty_prev.json() + assert eb["latest_available_date"] == "2026-11-10" + finally: + await drop_source(fx["id"]) + + +async def test_ai_suggest_metrics_from_catalog_and_kb_doc(client: AsyncClient, monkeypatch, tmp_path: Path): + fx = await _create_zhangyuan_fixture(tmp_path) + try: + async with SessionLocal() as session: + doc = Document( + collection="default", + title="指标公式总表", + source="test_metric_formula.md", + content="园区有效客流 = SUM(total_sys),仅统计 status=1 的记录。", + status="ready", + ) + session.add(doc) + await session.commit() + doc_id = doc.id + + class _FakeSuggestLLM: + async def ainvoke(self, messages): + prompt_text = str(messages[-1].content) + assert "指标公式总表" in prompt_text + assert "已绑定标准实体:zy_test_zone" in prompt_text + payload = { + "metrics": [ + { + "key": "zy_doc_footfall", + "name": "文档有效客流", + "aliases": ["有效客流"], + "unit": "人次", + "description": "依据指标公式总表提取", + "table_name": "footfall_daily", + "sql_expression": "SUM(total_sys)", + "date_column": "stat_date", + "filter_sql": "status = 1", + "dimensions": [{"key": "zone", "label": "区域", "column": "zone_code", "entity_key": "zy_test_zone"}], + }, + { + "key": "zy_hallucinated_col", + "name": "幻觉字段指标", + "table_name": "footfall_daily", + "sql_expression": "SUM(fake_not_in_table)", + }, + ] + } + return AIMessage(content=json.dumps(payload, ensure_ascii=False)) + + async def _fake_resolve(_session): + return _FakeSuggestLLM(), "mock-suggest" + + monkeypatch.setattr(catalog_assistant, "resolve_model", _fake_resolve) + + sug = await client.post( + "/api/semantic-metrics/suggest", + json={"source_id": fx["id"], "document_ids": [doc_id], "note": "提取客流核心指标"}, + ) + assert sug.status_code == 200, sug.text + sb = sug.json() + assert len(sb["candidates"]) == 1 and sb["candidates"][0]["key"] == "zy_doc_footfall" + assert len(sb["skipped"]) == 1 and sb["skipped"][0]["key"] == "zy_hallucinated_col" + + batch = await client.post("/api/semantic-metrics/batch", json={"items": sb["candidates"]}) + assert batch.status_code == 201 and len(batch.json()["created"]) == 1 + finally: + await drop_source(fx["id"]) + + +async def test_millisecond_deterministic_grounding_and_redaction(client: AsyncClient, tmp_path: Path): + fx = await _create_zhangyuan_fixture(tmp_path) + try: + await client.post( + "/api/semantic-metrics", + json={ + "key": "zy_footfall_card", + "name": "张园日客流", + "aliases": ["客流"], + "unit": "人次", + "source_id": fx["id"], + "table_name": "footfall_daily", + "sql_expression": "SUM(total_sys)", + "date_column": "stat_date", + "filter_sql": "status = 1", + "dimensions": [{"key": "zone", "label": "园区区域", "column": "zone_code", "entity_key": fx["entity_key"]}], + }, + ) + + async with SessionLocal() as session: + t0 = time.perf_counter() + bundle = await ground_question( + session, + f"{fx['name']} 西区四号楼今天客流咋样?", + datasource_ids=None, + restricted=False, + ) + elapsed_ms = (time.perf_counter() - t0) * 1000 + + assert elapsed_ms < 250, f"确定性预命中耗时过长: {elapsed_ms:.1f}ms" + assert any(m["key"] == "zy_footfall_card" for m in bundle.ui_summary["metrics"]) + ent_hits = [e for e in bundle.ui_summary["entities"] if e["entity_key"] == fx["entity_key"]] + assert ent_hits and ent_hits[0]["matched_member"]["target_codes"][fx["name"]] == ["Z_WEST_04"] + guardrail_kinds = {g["kind"] for g in bundle.ui_summary["guardrails"]} + assert {"business_date", "valid_filter", "stock_columns"} <= guardrail_kinds + assert "crowd_density" in bundle.system_context + assert "已遮罩" in bundle.system_context and "敏感手机号绝密备注" not in bundle.system_context + + # restricted=True(普通使用者视图)不泄露底层 SQL 表达式与物理编码 + restricted_bundle = await ground_question( + session, + f"{fx['name']} 西区四号楼今天客流咋样?", + datasource_ids=None, + restricted=True, + ) + assert "sql_expression" not in restricted_bundle.ui_summary["metrics"][0] + assert "target_codes" not in (restricted_bundle.ui_summary["entities"][0]["matched_member"] or {}) + finally: + await drop_source(fx["id"]) + + +async def test_fast_direct_ask_turn_with_metric_query_and_switch_to_deep( + client: AsyncClient, monkeypatch, tmp_path: Path, +): + fx = await _create_zhangyuan_fixture(tmp_path) + try: + assert is_platform_query(METRIC_QUERY) is True + + await client.post( + "/api/semantic-metrics", + json={ + "key": "zy_footfall_fast", + "name": "张园客流", + "aliases": ["客流"], + "unit": "人次", + "source_id": fx["id"], + "table_name": "footfall_daily", + "sql_expression": "SUM(total_sys)", + "date_column": "stat_date", + "filter_sql": "status = 1", + "dimensions": [{"key": "zone", "label": "园区区域", "column": "zone_code", "entity_key": fx["entity_key"]}], + }, + ) + + # 脚本化直查 Agent:第 1 步看到语义预命中注入的 zy_footfall_fast,调用 metric_query;第 2 步直接输出结论 + def _fast_decide(self, messages): + if any(isinstance(m, ToolMessage) for m in messages): + tool_msgs = [m for m in messages if isinstance(m, ToolMessage)] + raw_tool = str(tool_msgs[-1].content) + assert "【证据" in raw_tool + payload = json.loads(raw_tool[raw_tool.index("{") :]) + val = payload["rows"][0][0] + return AIMessage(content=f"西区四号楼 2026-11-10 有效客流为 {val} 人次。") + sys_prompt = str(messages[0].content) + assert "zy_footfall_fast" in sys_prompt and "Z_WEST_04" in sys_prompt + return AIMessage( + content="", + tool_calls=[ + { + "name": METRIC_QUERY, + "args": { + "metric_key": "zy_footfall_fast", + "date_from": "2026-11-10", + "date_to": "2026-11-10", + "filters": {"zone": "西区四号楼"}, + }, + "id": "tc_metric_1", + } + ], + ) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _fast_decide) + + conv_res = await client.post("/api/conversations", json={"kind": "chat", "title": "张园快速直查测试"}) + assert conv_res.status_code == 201 + conv_id = conv_res.json()["id"] + + # 1. 发起 depth="fast" 快速直查轮次 + start_res = await client.post( + "/api/chat/turns", + json={ + "conversation_id": conv_id, + "question": f"{fx['name']} 西区四号楼 2026-11-10 客流咋样?", + "datasource_ids": [fx["id"]], + "depth": "fast", + }, + ) + assert start_res.status_code == 202, start_res.text + turn_id = start_res.json()["turn_id"] + + await chat_job.manager.wait(turn_id, timeout=30.0) + async with SessionLocal() as session: + job = await session.get(ChatTurnJob, turn_id) + turn_row = await session.get(ConversationTurn, turn_id) + run_row = await session.get(Run, job.run_id) + snaps = list((await session.execute(select(Artifact).where(Artifact.run_id == job.run_id))).scalars().all()) + run_events = list( + (await session.execute(select(RunEvent).where(RunEvent.run_id == job.run_id).order_by(RunEvent.seq))) + .scalars() + .all() + ) + + assert job is not None and job.status == "succeeded" + assert turn_row is not None and turn_row.status == "done" + assert "1,500" in (turn_row.answer or "") or "1500" in (turn_row.answer or ""), turn_row.answer + assert turn_row.meta["depth"] == "fast" + assert turn_row.meta["queries"] == 1 + assert turn_row.meta.get("evidence") is True, "快速直查数字自动绑定为可点击溯源证据" + assert turn_row.meta["grounding"]["metrics"][0]["key"] == "zy_footfall_fast" + assert turn_row.review == {}, "快速直查模式跳过冗余的复核与报告重写" + assert [n["id"] for n in turn_row.graph["nodes"]] == ["q", "agent1", "report1", "out1"] + assert run_row is not None and run_row.status == "succeeded" + assert run_row.output["_evidence"]["report_node"] == "report1" + assert run_row.output["_evidence"]["fields"] == ["answer"] + checked_evts = [e for e in run_events if e.type == "report.checked"] + assert len(checked_evts) == 1 and checked_evts[0].data["ok"] is True + assert [e for e in run_events if e.type == "llm.start" and e.node_id == "report1"] == [], ( + "快速直查证据封装绝不发起额外 LLM 调用" + ) + assert any(e.data.get("code") == "report_answer_reused" for e in run_events) + q_snaps = [s for s in snaps if s.kind == "query_snapshot"] + assert q_snaps and await snapshot_owned(q_snaps[0].id, job.run_id, METRIC_QUERY) is True + + ev_res = await client.get(f"/api/runs/{job.run_id}/evidence") + assert ev_res.status_code == 200 + ev_payload = ev_res.json() + assert ev_payload["mode"] == "cited", ev_payload + assert len(ev_payload["reports"]) == 1 + + verify_res = await client.get(f"/api/runs/{job.run_id}/verify") + assert verify_res.status_code == 200 + assert verify_res.json()["ok"] is True, verify_res.json() + + events = await turn_log.read(turn_id, 0, limit=500) + stages = [e["data"]["stage"] for e in events if e["type"] == "stage"] + assert stages == ["ground", "run"], stages + grounding_ops = [e["data"] for e in events if e["type"] == "op" and e["data"].get("op") == "grounding"] + assert len(grounding_ops) == 1 + + # 2. 单轮一键「切换深度分析」(retry_of + depth="deep"):归档快速直查结果,重建完整工作流 + 报告 + 复核 + class _DeepCopilot: + async def astream(self, messages): + msg_text = str(messages[1][1]) + if "上线前自查" in msg_text: + yield es._line({"op": "done"}) + return + sql = "SELECT SUM(total_sys) AS gmv FROM footfall_daily WHERE stat_date = '2026-11-10' AND zone_code = 'Z_WEST_04' AND status = 1" + for op in es.graph_ops(fx["name"], sql): + yield es._line(op) + + es.use_copilot(monkeypatch, _DeepCopilot()) + es.use_report(monkeypatch, "深度分析报告:西区四号楼有效客流为 [[v:Q1.r0.gmv]] 人次。") + + upgrade_res = await client.post( + "/api/chat/turns", + json={ + "conversation_id": conv_id, + "retry_of": turn_id, + "mode": "retry", + "depth": "deep", + }, + ) + assert upgrade_res.status_code == 202, upgrade_res.text + await chat_job.manager.wait(turn_id, timeout=30.0) + + async with SessionLocal() as session: + upgraded = await session.get(ConversationTurn, turn_id) + + assert upgraded is not None and upgraded.status == "done" + assert "深度分析报告" in (upgraded.answer or "") + assert "1,500" in (upgraded.answer or "") or "1500" in (upgraded.answer or "") + assert upgraded.meta["depth"] == "deep" + assert len(upgraded.meta.get("attempts") or []) == 1, "切换深度分析后,原快速直查答案完整归档在 attempts 中" + prev_ans = upgraded.meta["attempts"][0].get("answer") or "" + assert "1,500" in prev_ans or "1500" in prev_ans + assert [n["id"] for n in upgraded.graph["nodes"]] != ["q", "agent1", "report1", "out1"], ( + "切换深度分析后重新构建了完整工作流(而非沿用直查图)" + ) + finally: + await drop_source(fx["id"]) + + +async def test_fast_direct_ask_clickable_evidence_shorthand_autolink_and_mask_guard( + client: AsyncClient, monkeypatch, tmp_path: Path, +): + """验证快速直查在零额外 LLM 调用下,支持显式标记归一、裸数字按行键消歧自动回绑、表名链接与遮罩列防护。""" + fx = await _create_zhangyuan_fixture(tmp_path) + try: + sql_tool_name = f"db_query__{fx['name']}" + + def _decide_with_mixed_citations(self, messages): + if any(isinstance(m, ToolMessage) for m in messages): + # 混合输出: + # 1) 显式无 r 前缀 + 大写列名:[[v:Q1.0.TOTAL_SYS]](对应 2026-11-09 的 1,200) + # 2) 裸数字 + 同行日期行键消歧:2026-11-10 的峰值密度 92、客流 1500 + # 3) 试图引用遮罩列:[[v:Q1.r0.secret_phone]](必须拦截为「已遮罩」) + # 4) 坏引用标记与句中 [[see:Q1]]:[[v:Q99.r0.ghost]] 不得向前端泄露 ⟦?v:...⟧ + # 5) 反引号物理表名:`footfall_daily` 自动转为实体链接 + return AIMessage( + content=( + "根据 [[see:Q1]] 查询 `footfall_daily` 结果:\n" + "- 2026-11-09 西区四号楼客流为 [[v:Q1.0.TOTAL_SYS]] 人次(联系电话 [[v:Q1.r0.secret_phone]]);\n" + "- 2026-11-10 西区四号楼客流为 1500 人次,峰值密度 92;\n" + "- 异常占位核验:[[v:Q99.r0.ghost]]。" + ) + ) + return AIMessage( + content="", + tool_calls=[ + { + "name": sql_tool_name, + "args": { + "sql": ( + "SELECT stat_date, zone_code, total_sys, crowd_density, secret_phone " + "FROM footfall_daily WHERE zone_code = 'Z_WEST_04' AND status = 1 " + "ORDER BY stat_date ASC" + ) + }, + "id": "tc_sql_mixed", + } + ], + ) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide_with_mixed_citations) + + conv_res = await client.post("/api/conversations", json={"kind": "chat", "title": "快速直查溯源边界测试"}) + conv_id = conv_res.json()["id"] + + start_res = await client.post( + "/api/chat/turns", + json={ + "conversation_id": conv_id, + "question": f"{fx['name']} 西区四号楼近两天客流与密度明细", + "datasource_ids": [fx["id"]], + "depth": "fast", + }, + ) + assert start_res.status_code == 202 + turn_id = start_res.json()["turn_id"] + await chat_job.manager.wait(turn_id, timeout=30.0) + + async with SessionLocal() as session: + job = await session.get(ChatTurnJob, turn_id) + turn_row = await session.get(ConversationTurn, turn_id) + run_row = await session.get(Run, job.run_id) + + assert turn_row is not None and turn_row.status == "done" + ans = turn_row.answer or "" + assert "[[v:" not in ans and "⟦?" not in ans, f"不应泄露原始标记或未解析占位符: {ans}" + assert "13800001111" not in ans and "13800003333" not in ans, "遮罩列严禁泄露真实手机号" + assert "已遮罩" in ans + assert "1,200" in ans and "1,500" in ans and "92" in ans + + doc_art_id = run_row.output["_evidence"]["doc_artifact"] + doc_res = await client.get(f"/api/artifacts/{doc_art_id}") + assert doc_res.status_code == 200 + doc = doc_res.json()["content"] + assert doc["stats"]["numbers_cited"] >= 3, doc["stats"] + all_segs = list(iter_segments(doc)) + det_cols = { + ((s.get("cite") or {}).get("locator", {}).get("row"), (s.get("cite") or {}).get("locator", {}).get("column")) + for s in all_segs + if s.get("kind") == "number" and s.get("state") == "deterministic" + } + # r0.total_sys (1200) 来自显式简写归一;r1.total_sys (1500) 与 r1.crowd_density (92) 来自裸数字自动回绑 + assert {(0, "total_sys"), (1, "total_sys"), (1, "crowd_density")} <= det_cols + assert any(s.get("kind") == "entity" and "footfall_daily" in (s.get("text") or "") for s in all_segs) + + verify_res = await client.get(f"/api/runs/{job.run_id}/verify") + assert verify_res.status_code == 200 and verify_res.json()["ok"] is True + finally: + await drop_source(fx["id"]) + + +def test_direct_evidence_unit_markdown_table_pct_wan_and_shorthand(): + """纯内存单元测试:单行无 r0 简写、百分比/万单位换算、手写 Markdown 表头按列消歧与 0 行数量词保护。""" + from app.chat.direct_evidence import normalize_and_bind_fast_citations + + snaps = { + "art_q1": { + "columns": ["zone_name", "gmv", "target_gmv", "conv_rate", "zero_diff"], + "column_types": ["TEXT", "NUMERIC", "NUMERIC", "REAL", "INTEGER"], + "rows": [ + ["西区", 125000, 125000, 0.126, 0], + ], + "mask_columns": [], + } + } + catalog_map = {"Q1": {"kind": "query", "artifact": "art_q1", "eid": "ev:query:art_q1"}} + raw = ( + "核心摘要:西区转化率达 12.6%,总成交 [[v:Q1.gmv|万]] 元(共返回 0 行异常记录,对比两天均值)。\n\n" + "| zone_name | gmv | target_gmv |\n" + "| --- | --- | --- |\n" + "| 西区 | 125000 | 125000 |\n" + ) + bound = normalize_and_bind_fast_citations(raw, catalog_map, loader=lambda aid: snaps.get(aid)) + # 1) 单行省略 .r0. 的 [[v:Q1.gmv|万]] 自动修复为 [[v:Q1.r0.gmv|万]] + assert "[[v:Q1.r0.gmv|万]]" in bound + # 2) 12.6% 自动识别小数比率列 conv_rate 并加 |pct + assert "[[v:Q1.r0.conv_rate|pct]]" in bound + # 3) 「0 行」不被误绑到 zero_diff=0,「两天」中文数字词不被误绑 + assert "0 行异常记录" in bound and "两天" in bound + # 4) Markdown 表格中 gmv 与 target_gmv 同为 125000,按表头列名各自精准绑定到对应列 + assert "| 西区 | [[v:Q1.r0.gmv]] | [[v:Q1.r0.target_gmv]] |" in bound + + # 5) 防止模型误将 [[v:...]] 当作脚注追加在裸数字后或句末造成二次重复渲染 + snaps2 = { + "art_q2": { + "columns": ["total_sys", "mmbl_sys"], + "column_types": ["INTEGER", "INTEGER"], + "rows": [[69133, 50617]], + "mask_columns": [], + } + } + cat2 = {"Q1": {"kind": "query", "artifact": "art_q2", "eid": "ev:query:art_q2"}} + dup_raw = ( + "当日总客流 69,133 人次,茂名北路 50,617 人次。[[v:Q1.r0.total_sys]] [[v:Q1.r0.mmbl_sys]]\n" + "紧邻重复测试:69,133 [[v:Q1.r0.total_sys]] 与 50,617([[v:Q1.r0.mmbl_sys]])。" + ) + deduped = normalize_and_bind_fast_citations(dup_raw, cat2, loader=lambda aid: snaps2.get(aid)) + assert deduped == ( + "当日总客流 [[v:Q1.r0.total_sys]] 人次,茂名北路 [[v:Q1.r0.mmbl_sys]] 人次。\n" + "紧邻重复测试:[[v:Q1.r0.total_sys]] 与 [[v:Q1.r0.mmbl_sys]]。" + ) diff --git a/backend/tests/test_metric_template_and_decompose.py b/backend/tests/test_metric_template_and_decompose.py new file mode 100644 index 00000000..8bb2cb35 --- /dev/null +++ b/backend/tests/test_metric_template_and_decompose.py @@ -0,0 +1,842 @@ +"""多表 / 参数化 SQL 模板语义指标(calc_mode="sql_template")与后台口径文档一键拆解工作流(SemanticDecomposeJob)端到端测试。""" +from __future__ import annotations + +import asyncio +import json +import sqlite3 +import uuid +from pathlib import Path +from typing import Any + +import pytest +from httpx import ASGITransport, AsyncClient +from langchain_core.messages import AIMessage +from sqlalchemy import delete, select + +from app.chat import job as chat_job +from app.chat.grounding import ground_question +from app.data import catalog, catalog_assistant, semantic_decompose +from app.data.engine import CATALOG_PROFILE_OPTION, MASK_COLUMNS_OPTION +from app.data.semantic_metrics import get_metric, metric_to_dict +from app.db.base import SessionLocal +from app.db.models import ConversationTurn, Document, Run +from app.db.models_chat import ChatTurnJob +from app.db.models_metrics import SemanticDecomposeJob, SemanticMetric +from app.db.models_ontology import CanonicalEntity +from app.engine.evidence import iter_segments +from app.engine.runner import run_manager +from app.main import app +from app.providers import mock_model +from app.tools.metrics import METRIC_QUERY +from tests.fixtures.sources import drop_source, sqlite_source + + +@pytest.fixture(autouse=True) +async def _lifecycle(): + await run_manager.setup() + yield + await semantic_decompose.shutdown() + await chat_job.shutdown() + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(SemanticDecomposeJob)) + await session.execute(delete(SemanticMetric)) + await session.execute(delete(CanonicalEntity).where(CanonicalEntity.key.like("mes_test_%"))) + await session.execute(delete(Document).where(Document.title.like("%OEE%"))) + await session.commit() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +async def _create_mes_fixture(tmp_path: Path) -> dict[str, str]: + """构造还原工业 OEE / TEEP 跨表场景的 SQLite 测试库(盲列 ATTRIBUTE01..34 + 不合格记录表 + 模具系数表 + 产线节拍表 + 遮罩列)。""" + db_path = tmp_path / f"mes_oee_{uuid.uuid4().hex[:6]}.db" + conn = sqlite3.connect(db_path) + try: + conn.executescript( + """ + CREATE TABLE mes_shift_daily ( + id INTEGER PRIMARY KEY, + stat_date TEXT NOT NULL, + line_code TEXT NOT NULL, + prod_code TEXT NOT NULL, + ATTRIBUTE01 REAL NOT NULL, -- 计划开班时长(秒) + ATTRIBUTE02 REAL NOT NULL, -- 计划内停机时长(秒) + ATTRIBUTE03 REAL NOT NULL, -- 故障与换模损失时长(秒) + ATTRIBUTE10 REAL NOT NULL, -- 合格入库数(件) + ATTRIBUTE34 REAL NOT NULL, -- 良品率(底表直接存百分数,如 98.5) + secret_phone TEXT, + is_valid INTEGER NOT NULL DEFAULT 1 + ); + + CREATE TABLE mes_bhgsj ( + id INTEGER PRIMARY KEY, + stat_date TEXT NOT NULL, + line_code TEXT NOT NULL, + scrap_qty REAL NOT NULL + ); + + CREATE TABLE mes_jzhmjxs ( + id INTEGER PRIMARY KEY, + prod_code TEXT NOT NULL, + mjxs REAL NOT NULL + ); + + CREATE TABLE iot_dn_productionline ( + line_code TEXT PRIMARY KEY, + line_name TEXT NOT NULL, + beat REAL NOT NULL -- 标准节拍(秒/件) + ); + + INSERT INTO iot_dn_productionline (line_code, line_name, beat) VALUES + ('L1', '一号冲压产线', 10.0), + ('L2', '二号焊接产线', 20.0); + + INSERT INTO mes_jzhmjxs (prod_code, mjxs) VALUES + ('P100', 1.2); + -- P200 故意不在模具系数表中,验证 COALESCE(mj.mjxs, 0.5) 兜底系数 + + INSERT INTO mes_shift_daily ( + stat_date, line_code, prod_code, + ATTRIBUTE01, ATTRIBUTE02, ATTRIBUTE03, ATTRIBUTE10, ATTRIBUTE34, + secret_phone, is_valid + ) VALUES + ('2026-03-01', 'L1', 'P100', 28800, 3600, 1200, 1800, 96.0, '13900001111', 1), + ('2026-03-01', 'L2', 'P200', 28800, 1800, 2000, 2000, 95.0, '13900002222', 1), + ('2026-03-02', 'L1', 'P100', 28800, 3600, 600, 2000, 98.0, '13900003333', 1), + ('2026-03-02', 'L1', 'P100', 99999, 0, 0, 9999, 100.0,'13900004444', 0); + + INSERT INTO mes_bhgsj (stat_date, line_code, scrap_qty) VALUES + ('2026-03-01', 'L1', 200), + ('2026-03-01', 'L2', 100), + ('2026-03-02', 'L1', 50); + """ + ) + conn.commit() + finally: + conn.close() + + src_name = f"mes_prod_{uuid.uuid4().hex[:6]}" + sid = await sqlite_source( + src_name, + db_path, + options={ + CATALOG_PROFILE_OPTION: {"enabled": True}, + MASK_COLUMNS_OPTION: "secret_phone", + }, + schema=True, + ) + ent_key = f"mes_test_line_{uuid.uuid4().hex[:4]}" + async with SessionLocal() as session: + session.add( + CanonicalEntity( + key=ent_key, + label="制造产线", + aliases=["产线", "生产线"], + members=[ + { + "id": "m_l1", + "value": "LINE_01", + "label": "一号冲压产线", + "aliases": ["一号产线", "1线"], + "source_codes": {src_name: "L1"}, + }, + { + "id": "m_l2", + "value": "LINE_02", + "label": "二号焊接产线", + "aliases": ["二号产线", "2线"], + "source_codes": {src_name: "L2"}, + }, + ], + bindings=[ + { + "id": "b_line", + "source_id": sid, + "source_name": src_name, + "table_name": "mes_shift_daily", + "column_name": "line_code", + "status": "confirmed", + "source": "human", + } + ], + version=1, + ) + ) + await session.commit() + + return {"source_id": sid, "source_name": src_name, "entity_key": ent_key} + + +@pytest.mark.asyncio +async def test_multi_table_sql_template_metric_crud_preview_and_guardrails(client: AsyncClient, tmp_path: Path): + """验证多表 JOIN + CTE + COALESCE + {{period_days}} 参数化模板指标的创建、安全拦截、实体转码试算与 restricted 脱敏。""" + fx = await _create_mes_fixture(tmp_path) + sid = fx["source_id"] + ent_key = fx["entity_key"] + try: + # 1) 安全红线拦截:写操作、未知占位符、不存在物理表、敏感遮罩列均必须 422 拒绝 + for bad_tpl in ( + "DELETE FROM mes_shift_daily", + "SELECT {{evil_slot}} SUM(s.ATTRIBUTE10) FROM mes_shift_daily s", + "SELECT SUM(s.ATTRIBUTE10) FROM mes_nonexistent_tbl s", + "SELECT COUNT(s.secret_phone) FROM mes_shift_daily s", + ): + r_bad = await client.post( + "/api/semantic-metrics", + json={ + "key": "bad_tpl_metric", + "name": "非法模板测试", + "source_id": sid, + "calc_mode": "sql_template", + "sql_template": bad_tpl, + }, + ) + assert r_bad.status_code == 422, f"未拦截非法模板: {bad_tpl} -> {r_bad.text}" + + # 2) 创建多表 OEE 精算指标(CTE + 多表 LEFT JOIN + COALESCE 0.5 模具兜底系数 + 参数化槽位) + oee_tpl = """ + WITH mj AS ( + SELECT prod_code, AVG(mjxs) AS mjxs + FROM mes_jzhmjxs + GROUP BY prod_code + ), + sc AS ( + SELECT stat_date, line_code, SUM(scrap_qty) AS bad_qty + FROM mes_bhgsj + GROUP BY stat_date, line_code + ) + SELECT + {{select_dims}} + ROUND( + SUM((s.ATTRIBUTE10 + COALESCE(sc.bad_qty, 0)) * pl.beat * COALESCE(mj.mjxs, 0.5)) + * 100.0 + / NULLIF(SUM(s.ATTRIBUTE01 - s.ATTRIBUTE02), 0) + * (SUM(s.ATTRIBUTE10) * 1.0 / NULLIF(SUM(s.ATTRIBUTE10 + COALESCE(sc.bad_qty, 0)), 0)), + 2 + ) AS mes_oee_multi + FROM mes_shift_daily s + JOIN iot_dn_productionline pl ON pl.line_code = s.line_code + LEFT JOIN mj ON mj.prod_code = s.prod_code + LEFT JOIN sc ON sc.stat_date = s.stat_date AND sc.line_code = s.line_code + WHERE 1=1 {{and_where}} + {{group_by}} + {{order_by}} + """.strip() + + r_create = await client.post( + "/api/semantic-metrics", + json={ + "key": "mes_oee_multi", + "name": "设备综合效率 OEE(跨表精算)", + "aliases": ["OEE", "综合效率"], + "unit": "%", + "source_id": sid, + "calc_mode": "sql_template", + "sql_template": oee_tpl, + "date_column": "s.stat_date", + "filter_sql": "s.is_valid = 1", + "dimensions": [ + {"key": "line_code", "label": "产线", "column": "s.line_code", "entity_key": ent_key}, + ], + }, + ) + assert r_create.status_code == 201, r_create.text + created_metric = r_create.json()["metric"] + assert created_metric["calc_mode"] == "sql_template" + assert created_metric["table_name"] == "mes_shift_daily" # 自动从模板首张物理表识别 + assert "[多表模板]" in created_metric["sql_expression"] + + # restricted=True 下必须隐藏底层 sql_template + async with SessionLocal() as session: + row = await get_metric(session, created_metric["id"]) + restricted_dict = metric_to_dict(row, restricted=True) + assert "sql_template" not in restricted_dict + assert "table_name" not in restricted_dict + + # 3) 在线试算:按产线分组 + 实体中文别名过滤(「一号产线」-> L1,且过滤掉 is_valid=0 脏数据) + r_prev_l1 = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": created_metric["id"], + "date_from": "2026-03-01", + "date_to": "2026-03-01", + "filters": {"line_code": "一号产线"}, + }, + ) + assert r_prev_l1.status_code == 200, r_prev_l1.text + prev_l1 = r_prev_l1.json() + assert prev_l1["entity_alignments"][0]["resolved_code"] == "L1" + # L1 2026-03-01: (1800+200)*10*1.2 / (28800-3600) * (1800/2000) * 100 = 24000 / 25200 * 0.9 * 100 = 85.71 + assert prev_l1["rows"] == [[85.71]] + + # L2 2026-03-01 走 COALESCE(mj.mjxs, 0.5) 兜底:(2000+100)*20*0.5 / (28800-1800) * (2000/2100) * 100 = 20000 / 27000 * 100 = 74.07 + r_prev_group = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": created_metric["id"], + "date_from": "2026-03-01", + "date_to": "2026-03-01", + "group_by": ["line_code"], + }, + ) + assert r_prev_group.status_code == 200, r_prev_group.text + grouped_rows = {r[0]: r[1] for r in r_prev_group.json()["rows"]} + assert grouped_rows == {"L1": 85.71, "L2": 74.07} + + # 4) 验证 {{period_days}} 动态自然周期天数模板(TEEP 日历秒数 = {{period_days}} * 86400 * 产线条数) + teep_tpl = """ + SELECT + {{select_dims}} + ROUND( + SUM(s.ATTRIBUTE01 - s.ATTRIBUTE02 - s.ATTRIBUTE03) * 100.0 + / NULLIF(({{period_days}}) * 86400.0 * COUNT(DISTINCT s.line_code), 0), + 2 + ) AS mes_teep + FROM mes_shift_daily s + WHERE 1=1 {{and_where}} + {{group_by}} + {{order_by}} + """.strip() + + r_teep = await client.post( + "/api/semantic-metrics", + json={ + "key": "mes_teep", + "name": "全员有效生产率 TEEP", + "unit": "%", + "source_id": sid, + "calc_mode": "sql_template", + "sql_template": teep_tpl, + "date_column": "s.stat_date", + "filter_sql": "s.is_valid = 1", + "dimensions": [{"key": "line_code", "label": "产线", "column": "s.line_code"}], + }, + ) + assert r_teep.status_code == 201, r_teep.text + teep_id = r_teep.json()["metric"]["id"] + + # 7 天区间(2026-03-01 ~ 2026-03-07):{{period_days}} 必须确定性编译为 7 + r_teep_7d = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": teep_id, + "date_from": "2026-03-01", + "date_to": "2026-03-07", + }, + ) + assert r_teep_7d.status_code == 200, r_teep_7d.text + assert "(7) * 86400.0" in r_teep_7d.json()["sql"] + + # 按日趋势(group_by_date=True):单日每行 {{period_days}} 必须确定性编译为 1 + r_teep_daily = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": teep_id, + "date_from": "2026-03-01", + "date_to": "2026-03-02", + "group_by_date": True, + }, + ) + assert r_teep_daily.status_code == 200, r_teep_daily.text + assert "(1) * 86400.0" in r_teep_daily.json()["sql"] + assert len(r_teep_daily.json()["rows"]) == 2 + finally: + await drop_source(sid) + + +@pytest.mark.asyncio +async def test_fast_direct_ask_with_sql_template_metric_produces_clickable_evidence( + client: AsyncClient, + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +): + """验证快速直查(depth='fast')命中多表 sql_template 指标后,经 metric_query 取数并生成可点击数字证据。""" + fx = await _create_mes_fixture(tmp_path) + sid = fx["source_id"] + ent_key = fx["entity_key"] + try: + oee_tpl = ( + "WITH mj AS (SELECT prod_code, AVG(mjxs) AS mjxs FROM mes_jzhmjxs GROUP BY prod_code), " + "sc AS (SELECT stat_date, line_code, SUM(scrap_qty) AS bad_qty FROM mes_bhgsj GROUP BY stat_date, line_code) " + "SELECT {{select_dims}} ROUND(SUM((s.ATTRIBUTE10 + COALESCE(sc.bad_qty, 0)) * pl.beat * COALESCE(mj.mjxs, 0.5)) * 100.0 " + "/ NULLIF(SUM(s.ATTRIBUTE01 - s.ATTRIBUTE02), 0) " + "* (SUM(s.ATTRIBUTE10) * 1.0 / NULLIF(SUM(s.ATTRIBUTE10 + COALESCE(sc.bad_qty, 0)), 0)), 2) AS mes_oee_fast " + "FROM mes_shift_daily s " + "JOIN iot_dn_productionline pl ON pl.line_code = s.line_code " + "LEFT JOIN mj ON mj.prod_code = s.prod_code " + "LEFT JOIN sc ON sc.stat_date = s.stat_date AND sc.line_code = s.line_code " + "WHERE 1=1 {{and_where}} {{group_by}} {{order_by}}" + ) + r_create = await client.post( + "/api/semantic-metrics", + json={ + "key": "mes_oee_fast", + "name": "产线跨表OEE", + "aliases": ["跨表OEE"], + "unit": "%", + "source_id": sid, + "calc_mode": "sql_template", + "sql_template": oee_tpl, + "date_column": "s.stat_date", + "filter_sql": "s.is_valid = 1", + "dimensions": [{"key": "line_code", "label": "产线", "column": "s.line_code", "entity_key": ent_key}], + }, + ) + assert r_create.status_code == 201 + + # 验证语义预命中包含 calc_mode="sql_template" 提示 + async with SessionLocal() as session: + bundle = await ground_question(session, question="查询 2026-03-01 一号产线的跨表OEE") + assert any(m["key"] == "mes_oee_fast" and m["calc_mode"] == "sql_template" for m in bundle.matched_metrics) + assert "多表参数化 SQL 模板" in bundle.system_context + + def _decide_oee(self: Any, messages: list[Any]) -> AIMessage: + has_tool_res = any(getattr(m, "type", "") == "tool" for m in messages) + if not has_tool_res: + return AIMessage( + content="", + tool_calls=[ + { + "id": "call_oee_tpl", + "name": METRIC_QUERY, + "args": { + "metric_key": "mes_oee_fast", + "date_from": "2026-03-01", + "date_to": "2026-03-01", + "filters": {"line_code": "一号产线"}, + }, + } + ], + ) + return AIMessage( + content="2026-03-01 一号冲压产线的跨表精算 OEE 为 **[[v:Q1.r0.mes_oee_fast]]**%。" + ) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide_oee) + + conv_res = await client.post("/api/conversations", json={"kind": "chat", "title": "跨表OEE直查测试"}) + conv_id = conv_res.json()["id"] + + r_turn = await client.post( + "/api/chat/turns", + json={ + "conversation_id": conv_id, + "question": "查询 2026-03-01 一号产线的跨表OEE", + "datasource_ids": [sid], + "depth": "fast", + }, + ) + assert r_turn.status_code == 202, r_turn.text + turn_id = r_turn.json()["turn_id"] + await chat_job.manager.wait(turn_id, timeout=30.0) + + async with SessionLocal() as session: + job = await session.get(ChatTurnJob, turn_id) + turn_row = await session.get(ConversationTurn, turn_id) + run_row = await session.get(Run, job.run_id) + + assert turn_row is not None and turn_row.status == "done" + assert "85.71" in (turn_row.answer or "") + assert "[[v:" not in (turn_row.answer or "") + + doc_art_id = run_row.output["_evidence"]["doc_artifact"] + doc = (await client.get(f"/api/artifacts/{doc_art_id}")).json()["content"] + assert doc["stats"]["numbers_cited"] >= 1 + segs = list(iter_segments(doc)) + assert any(s.get("kind") == "number" and "85.71" in str(s.get("text") or "") for s in segs) + + verify_res = await client.get(f"/api/runs/{job.run_id}/verify") + assert verify_res.status_code == 200 and verify_res.json()["ok"] is True + finally: + await drop_source(sid) + + +@pytest.mark.asyncio +async def test_background_document_decompose_workflow_and_one_click_apply( + client: AsyncClient, + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +): + """验证业务口径文档一键拆解后台任务(阶段进度 + 字段符号链式注入 + 知识库归档 + 一键应用四层资产)。""" + fx = await _create_mes_fixture(tmp_path) + sid = fx["source_id"] + src_name = fx["source_name"] + + captured_prompts: list[tuple[str, str]] = [] + + class _FakeDecomposeLLM: + async def ainvoke(self, msgs: list[Any]) -> AIMessage: + sys_txt = str(msgs[0].content) + usr_txt = str(msgs[1].content) + captured_prompts.append((sys_txt, usr_txt)) + + if "数据目录与字段字典拆解专家" in sys_txt: + payload = { + "tables": [ + { + "table": "mes_shift_daily", + "changes": [ + {"path": "label", "value": "产线班次日度生产宽表", "reason": "文档总表说明"}, + { + "path": "business_date", + "value": {"column": "stat_date", "rule": "按班次归属自然日"}, + "reason": "文档第 0 节", + }, + {"path": "valid_filter", "value": "is_valid = 1", "reason": "仅统计有效班次"}, + {"path": "columns.attribute01.label", "value": "计划开班时长", "reason": "文档符号 T_open"}, + {"path": "columns.attribute01.unit", "value": "秒", "reason": "文档符号 T_open"}, + {"path": "columns.attribute01.measure", "value": "flow", "reason": "时长可累加"}, + {"path": "columns.ATTRIBUTE34.label", "value": "班次良品率", "reason": "文档符号 Q_rate"}, + {"path": "columns.ATTRIBUTE34.unit", "value": "%", "reason": "百分数"}, + {"path": "columns.ATTRIBUTE34.measure", "value": "stock", "reason": "比率不可直接跨日相加"}, + { + "path": "columns.ATTRIBUTE34.note", + "value": "底表直接存百分数如 98.5,计算时需除以 100,切勿重复乘 100", + "reason": "文档存储陷阱提示", + }, + # 故意混入遮罩列测试自动拦截 + {"path": "columns.secret_phone.label", "value": "手机号", "reason": "测试遮罩过滤"}, + ], + } + ], + "guardrail_notes": [ + { + "title": "TEEP 物理红线", + "rule": "TEEP 超过 100% 必属配置或源数据错误;OEE 超过 200% 多为模具系数异常。", + "category": "redline", + } + ], + } + return AIMessage(content=json.dumps(payload, ensure_ascii=False)) + + if "语义指标建模专家" in sys_txt: + payload = { + "metrics": [ + { + "key": "mes_time_utilization", + "name": "时间稼动率(单表)", + "aliases": ["时间稼动率"], + "description": "实际开机时长除以负荷时长", + "unit": "%", + "calc_mode": "expression", + "table_name": "mes_shift_daily", + "sql_expression": "ROUND(SUM(ATTRIBUTE01 - ATTRIBUTE02 - ATTRIBUTE03) * 100.0 / NULLIF(SUM(ATTRIBUTE01 - ATTRIBUTE02), 0), 2)", + "sql_template": "", + "date_column": "stat_date", + "filter_sql": "is_valid = 1", + "dimensions": [{"key": "line_code", "label": "产线", "column": "line_code"}], + }, + { + "key": "mes_teep_doc", + "name": "全员有效生产率 TEEP(文档拆解)", + "aliases": ["TEEP"], + "description": "联合产线节拍与动态周期天数计算 TEEP", + "unit": "%", + "calc_mode": "sql_template", + "table_name": "mes_shift_daily", + "sql_expression": "", + "sql_template": ( + "SELECT {{select_dims}} " + "ROUND(SUM(s.ATTRIBUTE10 * pl.beat) * 100.0 / NULLIF(({{period_days}}) * 86400.0 * COUNT(DISTINCT s.line_code), 0), 2) AS mes_teep_doc " + "FROM mes_shift_daily s JOIN iot_dn_productionline pl ON pl.line_code = s.line_code " + "WHERE 1=1 {{and_where}} {{group_by}} {{order_by}}" + ), + "date_column": "s.stat_date", + "filter_sql": "s.is_valid = 1", + "dimensions": [{"key": "line_code", "label": "产线", "column": "s.line_code"}], + }, + { + # 故意混入不存在列的脏指标,验证自动过滤进 skipped + "key": "mes_hallucinated", + "name": "臆造列指标", + "calc_mode": "expression", + "table_name": "mes_shift_daily", + "sql_expression": "SUM(NON_EXISTENT_COL)", + }, + ] + } + return AIMessage(content=json.dumps(payload, ensure_ascii=False)) + + # 标准业务实体拆解专家 + ent_payload = { + "operations": [ + { + "op": "upsert_entity", + "entity_key": "mes_test_product_model", + "label": "产品型号", + "description": "车间生产产品型号标准实体", + "aliases": ["品号", "机种"], + "reason": "多表通过 prod_code 关联模具系数", + }, + { + "op": "upsert_binding", + "entity_key": "mes_test_product_model", + "entity_label": "产品型号", + "source_name": src_name, + "table_name": "mes_shift_daily", + "column_name": "prod_code", + "note": "班次产品编码", + "reason": "关联模具系数表", + }, + ] + } + return AIMessage(content=json.dumps(ent_payload, ensure_ascii=False)) + + async def _fake_resolve_model(_session: Any): + return _FakeDecomposeLLM(), "mock/decompose-pro" + + monkeypatch.setattr(catalog_assistant, "resolve_model", _fake_resolve_model) + + spec_md = """# TEEP / OEE 及相关指标公式总表 +## 0. 字段符号对照 +- `ATTRIBUTE01`:计划开班时长(秒) +- `ATTRIBUTE34`:班次良品率(底表存百分数,如 98.5) +## 1. 跨表 TEEP 公式 +自然日历时间 = 统计周期天数 × 86400 × 产线条数 +## 2. 判异红线 +TEEP > 100% 必属源数据错误。 +""" + try: + # 1) 测试上传附件接口可用 + r_att = await client.post( + "/api/semantic-metrics/attachments", + files={"file": ("oee_extra_notes.md", b"# Extra Note\nprod_code P100 = Model A\n", "text/markdown")}, + ) + assert r_att.status_code == 200, r_att.text + att_id = r_att.json()["attachment_id"] + + # 2) 发起后台一键拆解任务(202 Accepted) + r_start = await client.post( + "/api/semantic-metrics/decompose-jobs", + json={ + "source_id": sid, + "scopes": ["catalog", "metrics", "entities"], + "attachment_ids": [att_id], + "doc_title": "TEEP 与 OEE 指标公式总表", + "doc_text": spec_md, + "save_to_kb": True, + "note": "重点提取单表稼动率与跨表 TEEP", + }, + ) + assert r_start.status_code == 202, r_start.text + job_id = r_start.json()["job"]["id"] + + # 3) 轮询直至后台任务完成(验证进度 100% 与 4 个阶段全部成功) + final_job: dict[str, Any] | None = None + for _ in range(50): + r_job = await client.get(f"/api/semantic-metrics/decompose-jobs/{job_id}") + assert r_job.status_code == 200 + j = r_job.json()["job"] + if j["status"] in ("succeeded", "failed", "cancelled"): + final_job = j + break + await asyncio.sleep(0.04) + + assert final_job is not None + assert final_job["status"] == "succeeded", final_job.get("error") + assert final_job["progress"] == 100 + assert [s["status"] for s in final_job["steps"]] == ["succeeded", "succeeded", "succeeded", "succeeded"] + + # 验证 active 横幅接口返回最新待审阅任务 + r_active = await client.get("/api/semantic-metrics/decompose-jobs/active", params={"source_id": sid}) + assert r_active.status_code == 200 + assert r_active.json()["latest"]["id"] == job_id + + # 核心断言:阶段 2 提取出的 ATTRIBUTE01(计划开班时长,大写对齐!)与 ATTRIBUTE34 存储说明已在内存里链式传给阶段 3! + metric_stage_prompt = next(u for s, u in captured_prompts if "语义指标建模专家" in s) + assert "ATTRIBUTE01 (REAL) — 计划开班时长,单位:秒,度量:flow" in metric_stage_prompt + assert "底表直接存百分数" in metric_stage_prompt + + res = final_job["result"] + assert len(res["kb_documents"]) >= 1 + assert len(res["guardrail_notes"]) == 1 + assert len(res["metric_candidates"]) == 2 + assert len(res["metric_skipped"]) == 1 + # 确认 secret_phone 遮罩列被自动拦截,attribute01 大小写已自动对齐为 ATTRIBUTE01 + cat_paths = [c["path"] for c in res["catalog_patches"][0]["changes"]] + assert "columns.ATTRIBUTE01.label" in cat_paths + assert all("secret_phone" not in p for p in cat_paths) + assert len(res["entity_changes"]) == 2 + + # 4) 一键应用审阅结果 + r_apply = await client.post( + f"/api/semantic-metrics/decompose-jobs/{job_id}/apply", + json={"overwrite_existing_metrics": True}, + ) + assert r_apply.status_code == 200, r_apply.text + applied = r_apply.json()["applied"] + assert applied["catalog_applied_count"] >= 8 + assert applied["metrics_created_count"] == 2 + assert applied["entities_applied_count"] == 2 + + # 5) 核实三层资产均已真实落库且可立即执行在线试算 + async with SessionLocal() as session: + cat_entry = await catalog.read_entry(session, sid, "mes_shift_daily") + assert cat_entry is not None + vis = catalog.visible_notes(cat_entry.notes) + assert vis["columns"]["ATTRIBUTE01"]["label"]["value"] == "计划开班时长" + assert vis["columns"]["ATTRIBUTE34"]["measure"]["value"] == "stock" + + ent_row = ( + await session.execute(select(CanonicalEntity).where(CanonicalEntity.key == "mes_test_product_model")) + ).scalar_one_or_none() + assert ent_row is not None + assert ent_row.label == "产品型号" + + r_try_teep = await client.post( + "/api/semantic-metrics/preview", + json={ + "metric_id": "mes_teep_doc", + "date_from": "2026-03-01", + "date_to": "2026-03-02", + }, + ) + assert r_try_teep.status_code == 200, r_try_teep.text + assert r_try_teep.json()["row_count"] == 1 + assert r_try_teep.json()["rows"][0][0] > 0 + finally: + await drop_source(sid) + + +async def test_oracle_dialect_sql_compilation_and_validation(client: AsyncClient) -> None: + """回归验证 Oracle 方言下的多表 WITH CTE 模板、单表表达式、ROWNUM 行数限制、标识符不误加小写双引号与 DATE 字面量。""" + import sqlglot + + from app.data.guard import check as guard_check + from app.data.semantic_metrics import compile_metric_sql, create_metric + from app.db.models import DataSource + + async with SessionLocal() as session: + ora_ds = DataSource( + name=f"oracle_mes_{uuid.uuid4().hex[:6]}", + kind="oracle", + host="127.0.0.1", + port=1521, + database="ORCL", + username="mes_ro", + password="", + readonly=True, + options={"schema": "MES_PROD"}, + schema_cache={ + "schema": "MES_PROD", + "tables": { + "mes_kpi_shift_fact": { + "qualified": "MES_PROD.mes_kpi_shift_fact", + "schema": "MES_PROD", + "columns": [ + {"name": "factory_code", "type": "VARCHAR2(32 CHAR)", "nullable": False}, + {"name": "object_id", "type": "VARCHAR2(32 CHAR)", "nullable": False}, + {"name": "start_date_time", "type": "DATE", "nullable": False}, + {"name": "attribute01", "type": "NUMBER(18, 2)", "nullable": True}, + {"name": "attribute05", "type": "NUMBER(18, 2)", "nullable": True}, + {"name": "attribute14", "type": "NUMBER(18, 2)", "nullable": True}, + {"name": "attribute15", "type": "NUMBER(18, 2)", "nullable": True}, + {"name": "attribute54", "type": "NUMBER(18, 2)", "nullable": True}, + {"name": "lower_quoted_col", "type": "VARCHAR2(16 CHAR)", "nullable": True, "quote_name": True}, + ], + }, + "iot_prod_line_dim": { + "qualified": "MES_PROD.iot_prod_line_dim", + "schema": "MES_PROD", + "columns": [ + {"name": "line_code", "type": "VARCHAR2(32 CHAR)", "nullable": False}, + {"name": "beat", "type": "VARCHAR2(32 CHAR)", "nullable": True}, + ], + }, + }, + }, + ) + session.add(ora_ds) + await session.flush() + + tpl = ( + "WITH ln AS (SELECT line_code, AVG(TO_NUMBER(beat)) AS m_line FROM MES_PROD.iot_prod_line_dim GROUP BY line_code) " + "SELECT {{select_dims}} " + "ROUND(SUM((k.attribute14 + k.attribute15) * k.attribute54) * 100.0 / NULLIF(SUM(ln.m_line * k.attribute54), 0) " + "* (SUM(GREATEST(k.attribute01 - k.attribute05, 0)) / NULLIF({{period_days}} * 86400 * COUNT(DISTINCT k.object_id), 0)), 2) AS u_plan " + "FROM MES_PROD.mes_kpi_shift_fact k LEFT JOIN ln ON ln.line_code = k.object_id " + "WHERE 1=1 {{and_where}} {{group_by}} {{order_by}}" + ) + metric_row, _ = await create_metric( + session, + { + "key": "ora_u_plan", + "name": "计划综合利用率(Oracle跨表)", + "source_id": ora_ds.id, + "calc_mode": "sql_template", + "table_name": "mes_kpi_shift_fact", + "sql_template": tpl, + "date_column": "k.start_date_time", + "dimensions": [ + {"key": "factory_code", "label": "工厂", "column": "k.factory_code"}, + {"key": "lower_col", "label": "特殊小写列", "column": "k.lower_quoted_col"}, + ], + }, + ) + + # 1) 按工厂维度分组(无日期区间):验证无 LIMIT、无 CAST AS TEXT、无小写引号 "k"."factory_code"、WITH 保持在最外层 + sql_grouped, _ = compile_metric_sql( + metric_row, + source=ora_ds, + group_by=["factory_code"], + limit=30, + ) + assert "LIMIT" not in sql_grouped.upper() + assert "CAST(" not in sql_grouped.upper() + assert '"k"."factory_code"' not in sql_grouped + assert "k.factory_code" in sql_grouped + assert "TO_CHAR(k.start_date_time, 'YYYY-MM-DD')" in sql_grouped + assert sql_grouped.startswith("WITH ln AS") + assert "WHERE ROWNUM <= 30" in sql_grouped + guard_check(sql_grouped, readonly=True, dialect="oracle", source_name=ora_ds.name) + sqlglot.parse_one(sql_grouped, read="oracle") + + # 2) 带日期区间 + quote_name=True 的特殊小写列分组:验证 Oracle DATE 字面量与跨天 < DATE 'next_day' + sql_dated, _ = compile_metric_sql( + metric_row, + source=ora_ds, + date_from="2026-11-01", + date_to="2026-11-07", + group_by=["lower_col"], + limit=20, + ) + assert "k.start_date_time >= DATE '2026-11-01'" in sql_dated + assert "k.start_date_time < DATE '2026-11-08'" in sql_dated + assert 'k."lower_quoted_col"' in sql_dated + assert "7 * 86400" in sql_dated + sqlglot.parse_one(sql_dated, read="oracle") + + # 3) 单表 expression 模式:验证自动补齐 MES_PROD. 前缀、按表达式而非 GROUP BY 1 分组、套外层 ROWNUM + expr_row, _ = await create_metric( + session, + { + "key": "ora_open_hours", + "name": "计划开班总秒数", + "source_id": ora_ds.id, + "calc_mode": "expression", + "table_name": "mes_kpi_shift_fact", + "sql_expression": "SUM(attribute01)", + "date_column": "start_date_time", + "dimensions": [{"key": "factory_code", "label": "工厂", "column": "factory_code"}], + }, + ) + sql_expr, _ = compile_metric_sql( + expr_row, + source=ora_ds, + group_by_date=True, + group_by=["factory_code"], + limit=15, + ) + assert "FROM MES_PROD.mes_kpi_shift_fact" in sql_expr + assert "GROUP BY 1" not in sql_expr + assert "GROUP BY TO_CHAR(start_date_time, 'YYYY-MM-DD'), factory_code" in sql_expr + assert "LIMIT" not in sql_expr.upper() + assert "WHERE ROWNUM <= 15" in sql_expr + sqlglot.parse_one(sql_expr, read="oracle") + await session.rollback() + diff --git a/backend/tests/test_ontology_chat_penetration.py b/backend/tests/test_ontology_chat_penetration.py new file mode 100644 index 00000000..a371328b --- /dev/null +++ b/backend/tests/test_ontology_chat_penetration.py @@ -0,0 +1,255 @@ +"""Wave 2-c 单元测试:look 口径/表本体提示(按角色与授权脱敏)、Copilot 分析与本体提示词契约、P1 异常告警一键升级与最多 1 轮自动升级。""" +from __future__ import annotations + +import uuid +from datetime import date + +import pytest +from httpx import ASGITransport, AsyncClient +from sqlalchemy import delete, select + +import app.api.copilot as copilot +from app.analysis import contract as analysis_contract +from app.api import deps +from app.api.deps import Principal +from app.api.settings import anomaly_escalation_mode +from app.chat import drive as chat_drive +from app.chat import turn +from app.core.events import EventType +from app.db.base import SessionLocal +from app.db.models import DataSource, Run, RunEvent, Setting +from app.db.models_ontology import CanonicalEntity +from app.engine.runner import run_manager +from app.look.calibers import CaliberKind +from app.look.tables import TableKind +from app.main import app +from tests.fakes import auth_env +from tests.fixtures.acceptance import multi_source_ontology as mso +from tests.test_caliber_query_tool import grant_caliber + + +@pytest.fixture(autouse=True) +async def _cleanup(): + await run_manager.setup() + yield + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(CanonicalEntity)) + row = await session.get(Setting, "run") + if row is not None: + await session.delete(row) + await session.commit() + + +def _as_principal(username: str, role: str): + return deps.set_principal(Principal(username=username, role=role, verified=True, mode="local")) + + +async def test_look_caliber_and_table_ontology_hints_respect_confirmed_and_user_boundaries(tmp_path, scratch_source): + seeded = await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + wf_ops = seeded["workflow_ids"]["ops"] + wf_equip = seeded["workflow_ids"]["equip"] + wf_quality = seeded["workflow_ids"]["quality"] + + # 1) 搭建者(builder)查看口径详情:展示 1 跳已确认本体关联指标与底层数据源,绝不展示 proposed 边 + async with SessionLocal() as session: + cal_builder = await CaliberKind.load(session, compose=True, actor="builder") + found, missing = await cal_builder.resolve([{"source": wf_ops, "name": "good_output_qty"}]) + assert found and not missing + detail_builder, _ = await cal_builder.detail(found, budget=8000) + assert "本体关联指标" in detail_builder + assert "unplanned_downtime_min" in detail_builder + assert mso.SOURCE_EQUIP in detail_builder + + # load_rate_pct 上有 1 条 confirmed factor + 1 条 proposed upstream_driver:只显示 rated_hourly_qty + f_load, _ = await cal_builder.resolve([{"source": wf_ops, "name": "load_rate_pct"}]) + detail_load, _ = await cal_builder.detail(f_load, budget=8000) + assert "rated_hourly_qty" in detail_load + assert "unplanned_downtime_min" not in detail_load + + # 查看数据表详情:搭建者看到已确认的跨源标准实体桥(production_line: ops_shift <-> equip_master / quality_scrap) + src_rows = list((await session.execute(select(DataSource).where( + DataSource.name.in_([mso.SOURCE_OPS, mso.SOURCE_EQUIP]) + ))).scalars()) + tbl_builder = await TableKind.load(src_rows, trail={"actor": "builder"}) + t_refs, t_missing = await tbl_builder.resolve([{"source": mso.SOURCE_OPS, "name": "shift_output"}]) + assert t_refs and not t_missing + tbl_detail_builder, _ = await tbl_builder.detail(t_refs, budget=8000) + assert "跨源标准实体桥" in tbl_detail_builder + assert "production_line" in tbl_detail_builder + assert f"{mso.SOURCE_EQUIP}:line_specs.equip_line_id" in tbl_detail_builder + + # 2) 普通受限使用者(user):口径详情只列已授权邻居且隐去底层数据源名;表详情不泄露跨源物理表桥 + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma_look", "user") + await grant_caliber(wf_ops, 1, "uma_look", "use") + await grant_caliber(wf_equip, 1, "uma_look", "use") + # 注意:不给 uma_look 授权 wf_quality + + token = _as_principal("uma_look", "user") + try: + async with SessionLocal() as session: + cal_user = await CaliberKind.load(session, query=True, actor="uma_look") + # good_output_qty -> unplanned_downtime_min(已授权):可见邻居但隐去物理数据源名 + f_rate, _ = await cal_user.resolve([{"source": wf_ops, "name": "good_output_qty"}]) + detail_rate, _ = await cal_user.detail(f_rate, budget=8000) + assert "unplanned_downtime_min" in detail_rate + assert mso.SOURCE_EQUIP not in detail_rate + + # shift_scrap_qty -> ledger_scrap_units(未授权 wf_quality):绝不泄露未授权邻居 + f_rep, _ = await cal_user.resolve([{"source": wf_ops, "name": "shift_scrap_qty"}]) + detail_rep, _ = await cal_user.detail(f_rep, budget=8000) + assert "ledger_scrap_units" not in detail_rep + assert wf_quality not in detail_rep + + tbl_user = await TableKind.load(src_rows, trail={"actor": "uma_look"}) + u_refs, _ = await tbl_user.resolve([{"source": mso.SOURCE_OPS, "name": "shift_output"}]) + tbl_detail_user, _ = await tbl_user.detail(u_refs, budget=8000) + assert "跨源标准实体桥" not in tbl_detail_user + assert "equip_line_id" not in tbl_detail_user + finally: + deps.reset_principal(token) + finally: + await admin.aclose() + await auth_env.reset() + + +def test_copilot_prompt_contracts_for_ontology_and_analysis_off_switch(): + ref_on = copilot.node_reference(analysis_tools=True) + for tool_name in analysis_contract.TOOL_NAMES.values(): + assert tool_name in ref_on + assert tool_name in copilot.ANALYSIS_SHAPE_PROMPT + assert "ontology_neighbors" in ref_on and "source_health" in ref_on + assert "[[h:H1]]" in ref_on + assert "ontology_neighbors" in copilot._CHAT_USER_PROMPT and "inputs" in copilot._CHAT_USER_PROMPT + + # 评测关掉分析工具那一臂(analysis_tools=False):所有 analysis_* 与分析段落干净剥离 + ref_off = copilot.node_reference(analysis_tools=False) + for tool_name in analysis_contract.TOOL_NAMES.values(): + assert tool_name not in ref_off + assert "analysis_" not in ref_off + assert "[[a:" not in ref_off + + +async def test_anomaly_escalation_prompt_default_and_auto_single_rerun_cap(tmp_path, scratch_source): + await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + simple_graph = { + "nodes": [ + {"id": "in", "type": "input", "data": {"label": "入口", "config": {"fields": [{"name": "question"}]}}}, + {"id": "card", "type": "metrics", "data": {"label": "指标卡", "config": {"metrics": []}}}, + {"id": "out", "type": "output", "data": {"label": "出口", "config": {"fields": [{"name": "结果", "value": "135%"}]}}}, + ], + "edges": [{"source": "in", "target": "card"}, {"source": "card", "target": "out"}], + } + + async with SessionLocal() as session: + assert await anomaly_escalation_mode(session) == "prompt" + run1 = Run( + id=uuid.uuid4().hex, + status="succeeded", + graph=simple_graph, + output={"结果": "昨日星梭三线产线负荷率为 135.0%。"}, + ) + session.add(run1) + await session.flush() + session.add(RunEvent( + run_id=run1.id, + seq=1, + type=EventType.LOG, + node_id="card", + ts=1.0, + data={ + "level": "warn", + "code": "metric_contract_violated", + "metric": "load_rate_pct", + "reason": "指标值超出声明的范围", + "message": "指标「产线负荷率」触发数值契约告警:指标值超出声明的范围", + }, + )) + await session.commit() + run1_id = run1.id + + # 1) 默认 prompt 模式:返回正常复核说明 + anomaly_escalation 提示按钮,retry_instruction 为 None(不自动重跑烧额外 token) + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client: + r_prompt = await client.post("/api/copilot/review", json={"run_id": run1_id, "question": "昨天三线产线负荷率是多少"}) + assert r_prompt.status_code == 200, r_prompt.text + body_prompt = r_prompt.json() + assert body_prompt["retry_instruction"] is None + esc = body_prompt["anomaly_escalation"] + assert esc["available"] is True + assert esc["mode"] == "prompt" + assert esc["auto_escalate"] is False + assert esc["button_label"] == turn.ESCALATION_BUTTON_LABEL + assert "metric_contract_violated" in esc["signals"] + assert "ontology_neighbors" in esc["follow_up_instruction"] + + # 校验设置接口拒绝非法的 anomaly_escalation_mode,接受 "auto" + bad_put = await client.put("/api/settings", json={"values": {"run": {"anomaly_escalation_mode": "infinite"}}}) + assert bad_put.status_code == 422 + ok_put = await client.put("/api/settings", json={"values": {"run": {"anomaly_escalation_mode": "auto"}}}) + assert ok_put.status_code == 200 + + # 2) 切换到 auto 模式:attempt=0 给出升级指令且 escalation=True;attempt=1 严格封顶为 None(最多自动升级 1 轮!) + r_auto_0 = await client.post("/api/copilot/review", json={"run_id": run1_id, "question": "昨天三线产线负荷率是多少", "attempt": 0}) + body_auto_0 = r_auto_0.json() + assert body_auto_0["escalation"] is True + assert body_auto_0["anomaly_escalation"]["auto_escalate"] is True + assert body_auto_0["retry_instruction"] == body_auto_0["anomaly_escalation"]["follow_up_instruction"] + assert turn.escalate_after_review(body_auto_0, 0) is True + assert turn.escalate_after_review(body_auto_0, 1) is False + + r_auto_1 = await client.post("/api/copilot/review", json={"run_id": run1_id, "question": "昨天三线产线负荷率是多少", "attempt": 1}) + body_auto_1 = r_auto_1.json() + assert body_auto_1["anomaly_escalation"]["auto_escalate"] is False + assert body_auto_1["retry_instruction"] is None + + # 3) 验证 TurnDriver 在 auto 模式下端到端最多自动触发 1 次升级重跑(总共建图 2 次、跑图 2 次后停止) + seen_instructions: list[str] = [] + retry_kinds: list[str] = [] + + class _FakeDriver(chat_drive.TurnDriver): + async def _generate(self, instruction: str, base_graph: dict | None): + seen_instructions.append(instruction) + return [{"op": "final", "graph": simple_graph, "issues": [], "autorun": True, "next": "run"}], None + + async def _run(self, graph: dict, payload: dict | None = None): + async with SessionLocal() as s: + r = Run( + id=uuid.uuid4().hex, + status="succeeded", + graph=graph, + output={"结果": "135.0%"}, + ) + s.add(r) + await s.flush() + s.add(RunEvent( + run_id=r.id, + seq=1, + type=EventType.LOG, + node_id="card", + ts=1.0, + data={ + "level": "warn", + "code": "metric_contract_violated", + "metric": "load_rate_pct", + "reason": "指标值超出声明的范围", + "message": "指标「产线负荷率」触发数值契约告警:指标值超出声明的范围", + }, + )) + await s.commit() + self.turn.runs.append(r.id) + self.turn.run_id = r.id + self.last_run = r + return r + + async def on_retry(self, reason: str, *, kind: str, base_graph: dict | None, detail: str | None = None): + retry_kinds.append(kind) + + drv = _FakeDriver("昨天三线产线负荷率是多少", datasource_ids=[]) + settled_turn = await drv.drive() + assert settled_turn.path == "ran" + assert settled_turn.attempts == 1 + assert len(seen_instructions) == 2 + assert "ontology_neighbors" in seen_instructions[1] + assert retry_kinds == ["escalation"] diff --git a/backend/tests/test_ontology_eval.py b/backend/tests/test_ontology_eval.py new file mode 100644 index 00000000..fcbc518c --- /dev/null +++ b/backend/tests/test_ontology_eval.py @@ -0,0 +1,274 @@ +"""Wave 1-c 单元测试:三源虚构制造库确定性生成、ontology_suite.json 导入、零人工填数门禁、gold 试算与调查过程评分。""" +from __future__ import annotations + +import json +from datetime import date, datetime, timezone +from pathlib import Path + +import pytest +from sqlalchemy import delete + +from app.db.base import SessionLocal +from app.db.models_ontology import CanonicalEntity +from app.engine.runner import run_manager +from app.eval import cases, gold, judgements, score, transfer +from tests.fixtures.acceptance import multi_source_ontology as mso + +SUITE_PATH = Path(__file__).resolve().parent / "fixtures" / "eval" / "ontology_suite.json" + + +@pytest.fixture(autouse=True) +async def _engine_lifecycle(): + await run_manager.setup() + yield + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(CanonicalEntity)) + await session.commit() + + +def test_multi_source_ontology_builder_is_byte_deterministic(tmp_path): + a = mso.build(tmp_path / "run_a", today=date(2026, 10, 22)) + b = mso.build(tmp_path / "run_b", today=date(2026, 10, 22)) + assert a.ops_path.read_bytes() == b.ops_path.read_bytes() + assert a.equip_path.read_bytes() == b.equip_path.read_bytes() + assert a.quality_path.read_bytes() == b.quality_path.read_bytes() + + +def test_human_value_keys_and_invalid_investigation_fields_are_rejected(): + # 严禁在 reconcile / cochange / investigation 期望里手填判定、数值或驱动段(评测-D4) + for bad_exp in ( + {"kind": "verdict", "op": "reconcile", "params": {"measure": "a", "target_measure": "b"}, "verdict": "diverged"}, + {"kind": "verdict", "op": "cochange", "params": {"period": "d", "measure": "a", "driver_measure": "b"}, "judgement": "co_anomalous"}, + {"kind": "investigation", "status": "complete", "expected": "equip_master"}, + ): + with pytest.raises(cases.CaseInvalid): + cases.normalize_expectations([bad_exp], gold_kind="sql", case_kind="ask") + + # investigation 新增字段的类型与枚举范围校验 + with pytest.raises(cases.CaseInvalid): + cases.normalize_expectations( + [{"kind": "investigation", "min_ontology_hops": -1}], gold_kind=None, case_kind="ask" + ) + with pytest.raises(cases.CaseInvalid): + cases.normalize_expectations( + [{"kind": "investigation", "diagnosis_stage": "guesswork"}], gold_kind=None, case_kind="ask" + ) + + +async def test_ontology_suite_imports_and_computes_all_six_gold_cases(tmp_path, scratch_source): + await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + raw_suite = json.loads(SUITE_PATH.read_text(encoding="utf-8")) + + async with SessionLocal() as session: + plan = await transfer.plan_import(session, raw_suite) + assert len(plan.cases) == 6 + for planned in plan.cases: + assert planned.fields is not None, f"第 {planned.seq} 题导入校验未通过:{planned.reason}" + + # 固定截至时间 2026-10-22 10:00 +08:00(yesterday = 2026-10-21),逐题用真实探针算 gold + ctx = gold.Context(as_of=datetime(2026, 10, 22, 2, 0, 0, tzinfo=timezone.utc), tz="Asia/Shanghai") + outcomes = {} + for planned in plan.cases: + out = await gold.compute_gold(planned.fields, ctx) + assert out.ok, f"第 {planned.seq} 题算期望失败:{out.status} - {out.reason}" + outcomes[planned.seq] = out.sets[0].values + + # Case 1 (S1): EQ-L3 过期额定每小时产量 = 80.0 + assert outcomes[1]["stale_spec"]["value"] == 80.0 + # Case 2 (S2a): quality_scrap 昨日断更返回 0 行 + assert outcomes[2]["stalled_zero_rows"] == {"kind": "none", "rows": 0} + # Case 3 (S2b): 1000 倍量纲换算后 L4 超差 -> diverged + assert outcomes[3]["reconcile_energy"]["judgement"] == "diverged" + assert outcomes[3]["reconcile_energy"]["verdict"] == "diverged" + # Case 4 (S3): EQ-L2 有效运转率与非计划停机呈同期伴随异动 -> co_anomalous + assert outcomes[4]["cochange_l2"]["judgement"] == "co_anomalous" + assert outcomes[4]["cochange_l2"]["verdict"] == "co_anomalous" + # Case 5 (Control 1): L1 常规波动 -> normal (within_band) + assert outcomes[5]["normal_l1"]["judgement"] == "normal" + assert outcomes[5]["normal_l1"]["verdict"] == "within_band" + # Case 6 (Control 2): EQ-L4 主指标下滑但设备非计划停机平稳 -> target_normal + assert outcomes[6]["upstream_normal_l4"]["judgement"] == "target_normal" + assert outcomes[6]["upstream_normal_l4"]["verdict"] == "target_normal" + + +def test_score_grades_ontology_investigation_source_health_and_new_verdicts(): + exps = cases.normalize_expectations( + [ + { + "id": "inv", + "kind": "investigation", + "status": "complete", + "minimum_depth": 1, + "min_ontology_hops": 1, + "require_source_health": True, + "diagnosis_stage": "ontology_penetration", + "max_queries": 6, + }, + { + "id": "co", + "kind": "verdict", + "op": "cochange", + "params": {"period": "日期", "measure": "有效运转率", "driver_measure": "非计划停机分钟"}, + }, + ], + gold_kind="sql", + case_kind="ask", + ) + gold_values = { + "co": { + "kind": "verdict", + "status": "ok", + "op": "cochange", + "mode": None, + "method": "伴随异动", + "verdict": "co_anomalous", + "judgement": "co_anomalous", + "subjects": [], + "direction": None, + "phrase": "有效运转率超出常规波动,非计划停机分钟在同期同样超出常规波动(统计伴随关系,非因果断言)", + "result": {"op": "cochange", "status": "ok", "verdict": {"code": "co_anomalous", "subjects": [], "direction": None}}, + } + } + + # 1) 达标且引用了 A1 结论、台账带有 H1 健康检查记录 -> traced 通过 + good_answer = score.Answer( + run_id="r_good", + text="L2 有效运转率下滑,且上游非计划停机同步异动。", + analyses=[ + { + "artifact": "a" * 64, + "alias": "A1", + "op": "cochange", + "mode": None, + "method": "伴随异动", + "status": "ok", + "verdict": "co_anomalous", + "judgement": "co_anomalous", + "subjects": [], + "direction": None, + "phrase": "同期伴随异动", + "cited": ["phrase"], + "inputs": [], + } + ], + investigations=[ + { + "status": "complete", + "depth": 2, + "ontology_hops": 1, + "diagnosis_stage": "ontology_penetration", + "query_count": 4, + } + ], + source_healths=[ + {"artifact": "h" * 64, "node_id": "bot", "verdict": "healthy", "sources": ["equip_master"], "phrase": "正常"} + ], + ) + good_scores = score._expectation_scores(exps, gold_values, good_answer, "ran", None, {}) + assert [s["outcome"] for s in good_scores] == ["traced", "traced"] + + # 2) 未做健康检查、跳数 0、阶段不符且把伴随异动判成 target_normal -> 两项均判 wrong 并写明原因 + bad_answer = score.Answer( + run_id="r_bad", + text="未查出关联异动。", + analyses=[ + { + **good_answer.analyses[0], + "verdict": "target_normal", + "judgement": "target_normal", + } + ], + investigations=[ + { + "status": "complete", + "depth": 1, + "ontology_hops": 0, + "diagnosis_stage": "slice_localization", + "query_count": 2, + } + ], + source_healths=[], + ) + bad_scores = score._expectation_scores(exps, gold_values, bad_answer, "ran", None, {}) + assert [s["outcome"] for s in bad_scores] == ["wrong", "wrong"] + assert "未达到要求的本体穿透跳数" in bad_scores[0]["reason"] + assert "未执行关联数据源健康度检查" in bad_scores[0]["reason"] + assert "诊断阶段不符合期望" in bad_scores[0]["reason"] + assert judgements.judgement_code("reconcile", None, "missing_counterpart") == "diverged" + + +def test_ontology_tools_variant_preset_fingerprint_and_copilot_ablation(): + """W3-b.1:ontology_tools 预设对照、指纹兼容(开着时与历史完全一致)与助手关断门禁。""" + from app.api import copilot, evals + from app.eval import compare, variants + + on = variants.normalize_variant({}) + off = variants.normalize_variant({"ontology": {"tools": "off"}}) + assert on["ontology"] == {"tools": "on"} and off["ontology"] == {"tools": "off"} + models = {"assistant": "mock-fast", "writer": None} + legacy = {k: v for k, v in on.items() if k != "ontology"} + assert variants.variant_key(on, models) == variants.variant_key(legacy, models) + assert variants.variant_key(off, models) != variants.variant_key(on, models) + assert "本体穿透关" in variants.describe(off, models) + assert "本体穿透关" not in variants.describe(on, models) + + arms = variants.ontology_tools_preset({**on, "repeats": 3}) + assert [(a["label"], a["ontology"]["tools"], a["repeats"]) for a in arms] == [ + ("本体穿透开", "on", 3), + ("本体穿透关", "off", 3), + ] + assert "ontology_tools" in evals.PRESETS + + # 老指纹无 ontology_tools 与新默认 on 比较不报伪差异;on -> off 报「本体穿透:开 -> 关」 + assert compare.fingerprint_diff({"assistant_model": "m1"}, {"assistant_model": "m1", "ontology_tools": "on"}) == [] + diff = compare.fingerprint_diff({"ontology_tools": "on"}, {"ontology_tools": "off"}) + assert diff == [{"key": "ontology_tools", "label": "本体穿透", "before": "开", "after": "关"}] + + # copilot 工具清单与自查门禁在 ontology_tools=False 时彻底屏蔽 ontology_neighbors / source_health + cat_on = copilot._tool_catalog([], ontology_tools=True) + cat_off = copilot._tool_catalog([], ontology_tools=False) + assert "ontology_neighbors" in cat_on and "source_health" in cat_on + assert "ontology_neighbors" not in cat_off and "source_health" not in cat_off + ref_off = copilot.node_reference(analysis_tools=True, ontology_tools=False) + assert "ontology_neighbors" not in ref_off and "source_health" not in ref_off + + nodes = { + "in1": {"id": "in1", "type": "input", "data": {"label": "输入", "config": {"fields": []}}}, + "ag": { + "id": "ag", + "type": "agent", + "data": {"label": "排查", "config": {"prompt": "hi", "tools": ["ontology_neighbors", "source_health"]}}, + }, + "out1": {"id": "out1", "type": "output", "data": {"label": "输出", "config": {"fields": [{"name": "a", "value": "1"}]}}}, + } + edges = [{"source": "in1", "target": "ag"}, {"source": "ag", "target": "out1"}] + issues = copilot._blocking_issues(nodes, edges, ontology_tools=False) + assert issues and any(i["code"] == copilot.ONTOLOGY_TOOLS_OFF for i in issues) + + +def test_template_twelve_validates_and_publishes_as_governed(): + """W3-b.2:内置模板「⑫ 跨源指标异动与对账诊断」通过图校验并可直接按受管级别发布。""" + import copy + + from app.engine.governance import publish_issues + from app.engine.schema import GraphSpec, validate_graph + from app.seed import TEMPLATES + + name = "⑫ 跨源指标异动与对账诊断" + names = [t["name"] for t in TEMPLATES] + assert names.count(name) == 1 and names[-1] == name + tpl = next(t for t in TEMPLATES if t["name"] == name) + spec = GraphSpec.model_validate(copy.deepcopy({"nodes": tpl["nodes"], "edges": tpl["edges"]})) + report = validate_graph(spec) + assert report.ok, [i.message for i in report.issues if i.level == "error"] + errors = [i for i in publish_issues(spec, level="governed") if i.level == "error"] + assert errors == [], [i.message for i in errors] + agent_cfg = next(n for n in tpl["nodes"] if n["type"] == "agent")["data"]["config"] + assert set(agent_cfg["tools"]) >= { + "caliber_query", + "ontology_neighbors", + "source_health", + "analysis_reconcile", + "analysis_cochange", + } diff --git a/backend/tests/test_ontology_tools_and_auth.py b/backend/tests/test_ontology_tools_and_auth.py new file mode 100644 index 00000000..5e1841c4 --- /dev/null +++ b/backend/tests/test_ontology_tools_and_auth.py @@ -0,0 +1,346 @@ +"""Wave 2-a 单元测试:ontology_neighbors、source_health 工具、跨源实体键值对齐 align_caliber_inputs 与受限用户授权/脱敏边界。""" +from __future__ import annotations + +import uuid +from datetime import date + +import pytest +from sqlalchemy import delete + +from app.api import deps +from app.api.deps import Principal +from app.api.runs import _Projection +from app.auth import chat_policy +from app.chat.launch import bind_caliber_tool, user_chat_run +from app.core import artifact_store +from app.core.events import EventType +from app.data.entities import create_entity +from app.db.base import SessionLocal +from app.db.models import Run +from app.db.models_ontology import CanonicalEntity +from app.engine.runner import run_manager +from app.ledger import querycore +from app.tools.analysis import SCOPE_KEY, AnalysisScope, health_event_view +from app.tools.ontology import ( + ONTOLOGY_GUIDE, + ONTOLOGY_TOOLS, + align_caliber_inputs, + ontology_neighbors, + source_health_tool, +) +from app.tools.registry import ToolContext +from tests.fakes import auth_env +from tests.fixtures.acceptance import multi_source_ontology as mso +from tests.test_caliber_query_tool import grant_caliber + + +@pytest.fixture(autouse=True) +async def _engine_and_cleanup(): + await run_manager.setup() + yield + await run_manager.shutdown() + async with SessionLocal() as session: + await session.execute(delete(CanonicalEntity)) + await session.commit() + + +def _as_principal(username: str, role: str): + return deps.set_principal(Principal(username=username, role=role, verified=True, mode="local")) + + +async def test_ontology_neighbors_confirmed_only_and_restricted_user_filtering(tmp_path, scratch_source): + seeded = await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + wf_ops = seeded["workflow_ids"]["ops"] + wf_equip = seeded["workflow_ids"]["equip"] + wf_quality = seeded["workflow_ids"]["quality"] + + # 额外创建一个仅含 proposed 绑定的候选标准实体,验证运行期绝不混入已确认跨源桥 + async with SessionLocal() as session: + await create_entity( + session, + { + "key": "proposed_only_dim", + "label": "候选未确认维度", + "bindings": [ + { + "source_name": mso.SOURCE_OPS, + "table_name": "shift_output", + "column_name": "line_code", + "source": "ai", + }, + { + "source_name": mso.SOURCE_QUALITY, + "table_name": "scrap_ledger", + "column_name": "workcenter_code", + "source": "ai", + }, + ], + }, + actor="builder", + ) + await session.commit() + + # 1) 搭建者/管理员视角:查整卡 m_ops 能看到全部 3 条已确认邻居(factor / reconciles_with / upstream_driver), + # 而 load_rate_pct 上那条 proposed 的 upstream_driver 边绝不暴露 + scope = AnalysisScope(node_id="agent_1") + ctx = ToolContext( + run_id=uuid.uuid4().hex, + node_id="agent_1", + started_by="builder", + extra={SCOPE_KEY: scope}, + ) + res_card = await ontology_neighbors(ctx, workflow=wf_ops, card="m_ops", entity_filters={"production_line": "L2"}) + assert res_card["kind"] == "ontology_neighbors" + assert len(res_card["neighbors"]) == 3 + neighbor_metrics = {n["target"]["metric_id"] for n in res_card["neighbors"]} + assert neighbor_metrics == {"rated_hourly_qty", "unplanned_downtime_min", "ledger_scrap_units"} + assert scope.ontology_neighbors and scope.focal_calibers + + # 单查 load_rate_pct:只返回已确认的 factor(rated_hourly_qty),排除同指标上的 proposed upstream_driver + res_load = await ontology_neighbors(ctx, workflow=wf_ops, card="m_ops", metric_id="load_rate_pct") + assert [n["target"]["metric_id"] for n in res_load["neighbors"]] == ["rated_hourly_qty"] + + # 搭建者能看到已确认的跨源标准实体桥 production_line,看不到 proposed_only_dim + bridge_keys = {b["key"] for b in res_card["entity_bridges"]} + assert "production_line" in bridge_keys + assert "proposed_only_dim" not in bridge_keys + + # 2) 开启登录后受限普通使用者(user 角色):只授权 ops 与 equip,未授权 quality + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma_ont", "user") + await grant_caliber(wf_ops, 1, "uma_ont", "use") + await grant_caliber(wf_equip, 1, "uma_ont", "use") + + token = _as_principal("uma_ont", "user") + try: + # 查 ops 的 good_output_qty(含 upstream_driver -> equip,已授权)能返回 equip 邻居,且脱敏物理表列细节 + user_ctx = ToolContext(run_id=uuid.uuid4().hex, node_id="agent_u", started_by="uma_ont") + res_authorized = await ontology_neighbors( + user_ctx, + workflow=wf_ops, + card="m_ops", + metric_id="good_output_qty", + entity_filters={"production_line": "L2"}, + ) + assert len(res_authorized["neighbors"]) == 1 + nb = res_authorized["neighbors"][0]["target"] + assert nb["workflow_id"] == wf_equip and nb["metric_id"] == "unplanned_downtime_min" + assert "tables_by_source" not in nb + assert "sources" not in nb + assert all("bindings" not in b and "source_codes" not in str(b) for b in res_authorized["entity_bridges"]) + + # 查 ops 的 shift_scrap_qty(reconciles_with -> 未授权的 quality):未授权邻居被过滤并计入 omitted_unauthorized_count + res_filtered = await ontology_neighbors( + user_ctx, + workflow=wf_ops, + card="m_ops", + metric_id="shift_scrap_qty", + ) + assert res_filtered["neighbors"] == [] + assert res_filtered["omitted_unauthorized_count"] >= 1 + assert wf_quality not in str(res_filtered) + + # 直接点名未授权的焦点工作流 quality -> 明确拒绝 querycore_not_authorized + with pytest.raises(ValueError, match="querycore_not_authorized"): + await ontology_neighbors( + user_ctx, + workflow=wf_quality, + card="m_quality", + metric_id="ledger_scrap_units", + ) + finally: + deps.reset_principal(token) + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_source_health_tool_artifact_redaction_and_run_projection(tmp_path, scratch_source): + seeded = await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + wf_ops = seeded["workflow_ids"]["ops"] + wf_quality = seeded["workflow_ids"]["quality"] + yesterday = "2026-10-21" + + scope = AnalysisScope(node_id="agent_h") + run_id = uuid.uuid4().hex + ctx = ToolContext(run_id=run_id, node_id="agent_h", started_by="builder", extra={SCOPE_KEY: scope}) + res = await source_health_tool( + ctx, + workflow=wf_quality, + card="m_quality", + metric_id="ledger_scrap_units", + start=yesterday, + end=yesterday, + ) + assert res["verdict"] == "anomalous" + assert res["artifact"] + alias = scope.add_health(res["result"], res["artifact"]) + assert alias == "H1" + stored = artifact_store.load(res["artifact"]) + assert stored["verdict"] == "anomalous" + assert "inspector_id" not in str(stored) + assert "INSP-900" not in str(stored) + + # 验证 /api/runs 受限用户事件投影安全保留 health_artifact 摘要并剥离内部工件哈希 + ev_view = {"ref": alias, "artifact": res["artifact"], **health_event_view(res["result"], alias=alias)} + ev_dict = { + "type": str(EventType.TOOL_END), + "node_id": "agent_h", + "data": {"tool": "source_health", "health_artifact": ev_view, "preview": "H1"}, + } + projected = _Projection({"nodes": []}).event(ev_dict) + assert projected["data"]["health_artifact"]["ref"] == "H1" + assert projected["data"]["health_artifact"]["verdict"] == "anomalous" + assert "artifact" not in projected["data"]["health_artifact"] + + # 开启登录后普通使用者:允许按已授权口径查健康(脱敏物理表列),禁止查未授权数据源或未授权口径 + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma_health", "user") + await grant_caliber(wf_ops, 1, "uma_health", "use") + token = _as_principal("uma_health", "user") + try: + u_ctx = ToolContext(run_id=uuid.uuid4().hex, node_id="agent_u", started_by="uma_health") + ok_health = await source_health_tool( + u_ctx, + workflow=wf_ops, + card="m_ops", + metric_id="load_rate_pct", + start="2026-10-15", + end=yesterday, + ) + assert ok_health["verdict"] == "healthy" + assert "shift_output" not in str(ok_health) + + with pytest.raises(ValueError, match="querycore_not_authorized"): + await source_health_tool(u_ctx, source_name=mso.SOURCE_QUALITY) + + with pytest.raises(ValueError, match="querycore_not_authorized"): + await source_health_tool(u_ctx, workflow=wf_quality, card="m_quality") + finally: + deps.reset_principal(token) + finally: + await admin.aclose() + await auth_env.reset() + + +async def test_caliber_query_entity_inputs_alignment_and_chat_policy_whitelist(tmp_path, scratch_source): + seeded = await mso.seed_ontology_fixture(tmp_path, scratch_source, today=date(2026, 10, 22)) + wf_ops = seeded["workflow_ids"]["ops"] + wf_equip = seeded["workflow_ids"]["equip"] + yesterday = "2026-10-21" + + # 1) chat_policy 白名单与 chat/launch 自动补绑验证 + assert ONTOLOGY_TOOLS.issubset(chat_policy.CHAT_BUILTIN_TOOLS) + assert "ontology_neighbors" in ONTOLOGY_GUIDE.text and "source_health" in ONTOLOGY_GUIDE.text + graph = { + "nodes": [ + {"id": "in", "type": "input", "data": {"label": "入口", "config": {"fields": [{"name": "question"}]}}}, + {"id": "bot", "type": "agent", "data": {"label": "分析", "config": {"prompt": "{{ input.question }}", "tools": []}}}, + {"id": "out", "type": "output", "data": {"label": "出口", "config": {"fields": [{"name": "a", "value": "{{ nodes.bot.text }}"}]}}}, + ], + "edges": [{"source": "in", "target": "bot"}, {"source": "bot", "target": "out"}], + } + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma_bind", "user") + await grant_caliber(wf_ops, 1, "uma_bind", "use") + async with SessionLocal() as session: + bound = await bind_caliber_tool(session, graph, "uma_bind") + finally: + await admin.aclose() + await auth_env.reset() + bot_tools = next(n for n in bound["nodes"] if n["id"] == "bot")["data"]["config"]["tools"] + assert {"caliber_query", "ontology_neighbors", "source_health"}.issubset(set(bot_tools)) + assert chat_policy.chat_graph_problem(bound) is None + + # 2) align_caliber_inputs:L2 -> EQ-L2 确定性翻译;未知值绝不模糊猜测 + async with SessionLocal() as session: + aligned, records = await align_caliber_inputs( + session, + workflow_id=wf_equip, + card_id="m_equip", + inputs={"stat_day": yesterday}, + entity_inputs={"production_line": "L2"}, + from_source=mso.SOURCE_OPS, + ) + assert aligned["equip_line"] == "EQ-L2" + assert records and records[0]["target_value"] == "EQ-L2" + + # 未知产线编码 L99 绝不子串匹配成 L1/L2 + untouched, empty_records = await align_caliber_inputs( + session, + workflow_id=wf_equip, + card_id="m_equip", + inputs={"stat_day": yesterday}, + entity_inputs={"production_line": "L99"}, + from_source=mso.SOURCE_OPS, + ) + assert "equip_line" not in untouched + assert empty_records == [] + + # 3) 真跑父 Run 下的 caliber_query(entity_inputs={"production_line": "L2"}),验证算出 EQ-L2 非计划停机 96.0 分钟 + async with SessionLocal() as session: + parent = Run( + status="running", + run_class="exploratory", + graph=bound, + input={"question": "排查二线停机"}, + started_by="builder", + ) + session.add(parent) + await session.commit() + parent_id = parent.id + + emitted_events: list[tuple] = [] + ctx = ToolContext( + run_id=parent_id, + node_id="bot", + started_by="builder", + emit=lambda etype, **kw: emitted_events.append((etype, kw)), + ) + cq_res = await querycore.caliber_query( + ctx, + workflow=wf_equip, + card="m_equip", + metric_ids=["unplanned_downtime_min"], + inputs={"stat_day": yesterday}, + entity_inputs={"production_line": "L2"}, + from_source=mso.SOURCE_OPS, + ) + assert cq_res["ok"] is True + assert cq_res["ontology_alignment"][0]["target_value"] == "EQ-L2" + metrics_by_id = {m["id"]: m for m in cq_res["metrics"]} + assert metrics_by_id["unplanned_downtime_min"]["value"] == pytest.approx(96.0) + + # 4) 验证 caliber_query 对越界指标(S1:L3 load_rate_pct = 135% > 100%)透传 contract_findings 并发 metric_contract_violated 日志 + cq_s1 = await querycore.caliber_query( + ctx, + workflow=wf_ops, + card="m_ops", + metric_ids=["load_rate_pct"], + inputs={"shift_day": yesterday, "line_code": "L3"}, + ) + assert cq_s1["ok"] is True + load_metric = next(m for m in cq_s1["metrics"] if m["id"] == "load_rate_pct") + assert load_metric["value"] == pytest.approx(135.0) + assert load_metric.get("contract_findings") + assert any(kw.get("code") == "metric_contract_violated" for _t, kw in emitted_events) + + # 5) 验证 user_chat_run 对有授权口径的普通使用者自动补齐 ontology 工具 + admin = await auth_env.turn_on_local() + try: + await auth_env.make_user("uma_launch", "user") + await grant_caliber(wf_ops, 1, "uma_launch", "use") + token = _as_principal("uma_launch", "user") + try: + async with SessionLocal() as session: + _mem, _opts, patched_graph = await user_chat_run(session, graph, "uma_launch") + patched_tools = next(n for n in patched_graph["nodes"] if n["id"] == "bot")["data"]["config"]["tools"] + assert {"caliber_query", "ontology_neighbors", "source_health"}.issubset(set(patched_tools)) + finally: + deps.reset_principal(token) + finally: + await admin.aclose() + await auth_env.reset() diff --git a/docs/en/analysis.md b/docs/en/analysis.md index 8e55d826..e911c6f4 100644 --- a/docs/en/analysis.md +++ b/docs/en/analysis.md @@ -81,6 +81,14 @@ When everything passes (or can't be checked), the periods are comparable; with o When a change decomposition is given two queries, it runs this check automatically first; when the fluctuation baseline, the trend test, or a change decomposition over a single query checks whether the current period is complete, it uses the whole-period item of this check. It also runs once automatically when a caliber card metric uses two queries of the same shape that differ only in their dates (this week versus last week), with the result attached to the metric (see [Caliber cards](evidence.md#caliber-cards)). +### Cross-source reconciliation and co-movement + +Alongside the five single-source analyses, cross-source ontology investigation adds two deterministic cross-metric operators and a data-source health probe: + +- **Cross-source reconciliation (`reconcile`)**: compares two `reconciles_with` mirror calibers or queries row by row along aligned entity keys. It supports deterministic unit scaling (`scale`, such as `1000` between kWh and MWh) plus absolute and relative tolerances, returning `aligned`, `diverged` (naming the out-of-tolerance segments), or `missing_counterpart`. +- **Co-movement (`cochange`)**: tests whether a focal metric and an `upstream_driver` series both exceed their robust historical fluctuation bands (median and MAD) within a configured lag window (`lag_periods` from `0` to `3`), reporting descriptive Spearman rank correlation alongside verdicts `co_anomalous`, `target_normal` (ruling out that upstream driver), or `opposite_move`. Both the verdict phrase and the analysis claim check frame `cochange` strictly as **synchronous statistical co-movement**, forbidding causal assertions ("caused by", "led to") unless backed by an explicit knowledge-base rule. +- **Source health probe (`source_health`)**: performs read-only checks on target data sources or caliber backing tables for stalled dates (`date_stalled`), date gaps (`date_gap`), recent row-volume drops (`volume_drop`), and uncataloged new code values (`codes_new`). Results are sealed as `H1`, `H2`, ... artifacts, cited with `[[h:H1]]` / `[[see:H1]]`, and inspected in the evidence drawer. + ## When an analysis can't be done An analysis that can't be done doesn't fail the agent or the node. It is recorded as a conclusion, with a verdict phrase along the lines of "Fluctuation baseline not done: only 5 periods of history, at least 8 needed", and it goes into the ledger and can be cited and checked: diff --git a/docs/en/ask-data.md b/docs/en/ask-data.md index 73cefbb0..866df9e7 100644 --- a/docs/en/ask-data.md +++ b/docs/en/ask-data.md @@ -36,6 +36,14 @@ When the question asks why, how something changed, what dragged it down, what co - During its self-check, Copilot recognizes analytical questions with a fixed lexicon that collects only explicit phrasings. When the question is analytical but the agent that queries data has no analysis tools, the problem goes back to Copilot for one round of fixes; if the tools are still missing after that round, the graph runs as usual with a warning. - When an analysis couldn't be done (not enough history, the current period isn't over, and so on), or judgment words still don't cite a matching conclusion after the rewrite, the review only writes a note and doesn't start over automatically (see [Output review](#output-review)). +### Cross-source ontology penetration and anomaly escalation + +When a metric hits a contract violation, empty query or metric data, cross-source reconciliation divergence, or an anomalous related data source, Ask Data can investigate across data sources along confirmed business ontology links: + +- **Three-stage diagnostic discipline**: the agent first calls `ontology_neighbors` to inspect confirmed one-hop metric links and canonical entity bridges, and calls `source_health` to check external tables for stalled dates, date gaps, volume drops, or unrecognized new codes. When source health or cross-source reconciliation (`analysis_reconcile`) already explains the anomaly, the report cites `[[h:H1]]` or `[[a:A1]]` and stops early instead of breaking down business dimensions on faulty data. Only when source health passes does the agent localize the driving slice in the primary source and query neighbor calibers through `caliber_query` (with deterministic entity-code translation in `inputs`) for co-movement checks (`analysis_cochange`). +- **Anomaly escalation (prompt by default)**: when a simple lookup turn triggers a hard anomaly signal, it adds zero extra overhead by default and surfaces a one-click escalation button in the turn review actions (`mode: "escalate"`). Under Settings -> Preferences, cross-source anomaly investigation can also be switched to automatic escalation (at most 1 automatic retry). +- **Status and role gates**: runtime penetration traverses only `confirmed` / `verified` ontology links and canonical entity bindings (`proposed` candidates never fire at runtime). Restricted users see and invoke only neighbor calibers pinned by apps they are authorized to use, with zero exposure of unauthorized workflow IDs or physical table and column names. + ## Output review After a run ends, rules scan the event stream first, and a model review runs only when they find an anomaly. The review may restructure the answer, but it **must not introduce numbers that aren't in the original answer**. diff --git a/docs/en/data-catalog.md b/docs/en/data-catalog.md index 91547d3e..05f1b3ef 100644 --- a/docs/en/data-catalog.md +++ b/docs/en/data-catalog.md @@ -194,4 +194,20 @@ Scheduled Maintenance on the data source card: - Choose the steps (introspect the schema, profile the tables that need it, value observation; several can be chosen) and an off-peak time window; this is saved as a schedule whose target is the data source. There is none by default. - It queues with drafting and profiling on the same data source, and steps that didn't run record the reason as it is. -- Schedules of this kind don't accept webhooks (they return 422); notifications go through channel subscriptions under Settings → Notifications. +- Schedules of this kind don't accept webhooks (they return 422); notifications go through channel subscriptions under Settings -> Notifications. + +## Canonical business entity bridges + +Different business databases often represent the same real-world object with different table names, column names, and code prefixes (for example, `L1` in `mfg_ops` versus `EQ-L1` in `equip_master`). The Data Catalog header provides a Canonical Entities view (`?view=entities`) to govern cross-source canonical business entities (`CanonicalEntity`): + +- **Two-column governance**: the left pane manages entity keys (such as `prod_line`), display names, and lifecycle status; the right pane maintains physical table-column bindings (`bindings`), caliber input parameter mappings (`caliber_params`), and cross-source member code dictionaries (`members`). +- **Candidate review and runtime gate**: mappings drafted from documentation or proposed by collaborators start as `proposed` and can be confirmed or rejected item by item in the Canonical Entities view. Only `confirmed` / `verified` bindings and parameter mappings participate in runtime cross-source input translation (`align_caliber_inputs`) and Copilot entity-bridge hints. +- **Caliber semantic reference**: in a caliber's query semantics editor, dimensions can directly select a registered `entity_key` instead of duplicating cross-database key mappings on every caliber. + +### Agent-assisted governance and business documents + +On the Canonical Entities page, alongside manual form editing, maintainers can govern cross-source entities through an interactive assistant and background discovery jobs: + +- **Entity Assistant**: click Entity Assistant in the header to open the right-hand chat drawer (`POST /api/ontology/entities/assistant`). By default, the assistant scopes its context strictly to the current data source (preventing tables or calibers from unrelated business domains from leaking in); maintainers can expand the scope selector at the top of the drawer to check additional data sources when cross-source alignment is needed. Within the selected sources, the assistant inspects schemas, catalog entries, and caliber inputs (`inspect_sources`), runs read-only masked SQL queries to verify live code values (`run_query`), reads attached business documents (`read_document`), and emits structured diff proposals (`propose_entity_changes`). Proposals never write to the database automatically; maintainers keep or drop individual items and click Save Changes to apply them as `confirmed` with optimistic-concurrency version checks (`POST /api/ontology/entities/apply-patch`). +- **Scan for Candidate Entities**: click Scan for Candidate Entities (`POST /api/ontology/discovery-jobs`), which defaults to the current data source and allows checking additional sources in the same business domain. The background scan inspects the selected data sources, linked calibers, and documents. Discovered bindings and caliber parameter mappings are always recorded as `proposed` (`source="ai"`), never overwrite `confirmed`, `verified`, or `rejected` items, and remain gated out of live runtime cross-source penetration until reviewed and confirmed by a maintainer. +- **Business document and mapping sheet attachments**: both the Entity Assistant drawer and the Scan for Candidate Entities dialog accept `.md`, `.docx`, `.pdf`, `.xlsx`, and `.csv` business rules or master-data code mapping sheets (`POST /api/ontology/entities/attachments`), as well as existing Knowledge Base documents. Maintainers can check "Also save to Knowledge Base for future reuse" (`save_to_kb`) and pick a target collection so an uploaded mapping sheet immediately serves both entity alignment and downstream Ask-Data retrieval. diff --git a/docs/en/development.md b/docs/en/development.md index e47ac90d..64d03b71 100644 --- a/docs/en/development.md +++ b/docs/en/development.md @@ -122,7 +122,7 @@ It can switch between "normal / time out after a successful write / 500 / 4xx", ## Frontend checks ```bash -# 43 items, 8 lanes in parallel by default. They connect to 5273 / 8000, so start ./scripts/dev.sh first +# 45 items, 8 lanes in parallel by default. They connect to 5273 / 8000, so start ./scripts/dev.sh first node scripts/check-all.mjs # Start 2 extra "backend + vite" stacks used only by the checks, each with its own copy of the data, about 6.5 minutes; editing code while they run doesn't interrupt them CHECK_DATA_SRC= node scripts/check-all.mjs --stacks 2 --lanes 12 @@ -135,7 +135,7 @@ node scripts/check-all.mjs evidence publish - `scripts/e2e-check.mjs` really starts a run (Mock, costs nothing) and leaves records in the database, so it isn't part of check-all. - `scripts/check-auth.mjs` (login, navigation collapsed by role, 401 redirecting to login) has to run on its own against a separate service with local-account login turned on, so it isn't part of check-all either. -The 43 `check-all` items, in the order of `ORDER` in `scripts/check-all.mjs`: +The 45 `check-all` items, in the order of `ORDER` in `scripts/check-all.mjs`: | Category | Checks | |---|---| @@ -144,7 +144,7 @@ The 43 `check-all` items, in the order of `ORDER` in `scripts/check-all.mjs`: | Shell, answer stream, and run states | `shell` `stream` `evidence` (clickable evidence) `run-states` (node cards) `canvas-fx` (canvas surface layer) | | Pages | `studio` `publish` (pre-publish check and autofix) `chat` `runs` `manage` `versions` (uploaded spreadsheet versions) `catalog` (data catalog) `catalog-loop` (Table Copilot, review queue, export and import) `catalog-profile` (per-table data profiling jobs) `catalog-changes` (changes, the changes section in table details, scheduled maintenance, the background job bar) `ui` (end to end, with real data) | | Review suite and exports | `schedules` (schedules) `compare` (run comparison) `verify` (double-blind recomputation, adversarial review) `inquiry` (approval inquiry) `challenge` (adversarial review) `bundle` (verifiable report) `whatif` (what-if sandbox) `report-export` (report export) | -| Evaluation and caliber ledger | `evals` (test suites, adding questions, starting and progress, results, comparison and A/B, caliber hits and repetition) `ledger` (the Caliber step in evidence, turn summaries, issuance and reconciliation, distillable questions) | +| Evaluation and caliber ledger | `evals` (test suites, adding questions, starting and progress, results, comparison and A/B, caliber hits and repetition) `ledger` (the Caliber step in evidence, turn summaries, issuance and reconciliation, distillable questions) `caliber-drafts` (caliber draft workbench, incremental re-import, and natural-language caliber change) `ontology` (canonical business entities, caliber ontology topology, source health evidence chain, anomaly escalation, and ontology penetration attribution) | | App platform | `apps` (app pages, stamps, clicking numbers to see provenance, entry validation, instance pages) `inbox` (joint sign-off progress, timeouts, the hash card for action confirmation, verification) `app-editor` (app editing, derivation, checks, choosing a disposition at publish time, Copilot) `capabilities` (capabilities, endpoints, identity, notifications, audit) `access-keys` (access keys) `share` (share links and the /s page) `blueprint` (creating apps, blueprint cards, trial runs, publish summaries) `personal` (personal apps) `records` (record list) `files` (file controls) | ### What the three verification layers cover diff --git a/docs/en/evaluation-and-ledger.md b/docs/en/evaluation-and-ledger.md index 2d838d43..327c4a62 100644 --- a/docs/en/evaluation-and-ledger.md +++ b/docs/en/evaluation-and-ledger.md @@ -31,12 +31,13 @@ Rules: ### Run an evaluation -1. Choose the variants: Copilot model, writing model, judge on or off, catalog (current / snapshot / verified only / off), analysis tools (on / off, on by default), and how many repetitions. -2. Check the estimated cost, then start. The Catalog contribution preset runs "current vs. off" in one go, and the Analysis tools contribution preset runs "analysis tools on vs. off". +1. Choose the variants: Copilot model, writing model, judge on or off, catalog (current / snapshot / verified only / off), analysis tools (on / off, on by default), ontology penetration (on / off, on by default), and how many repetitions. +2. Check the estimated cost, then start. The Catalog contribution preset runs "current vs. off" in one go, the Analysis tools contribution preset runs "analysis tools on vs. off", and the Ontology penetration contribution preset runs "ontology penetration on vs. off". - Evaluations run in the background, and each question goes exactly the way a user's question would in Ask Data (graph building, run, review). Questions that stop at an approval aren't approved on anyone's behalf and are recorded as they are. - When Copilot returns only thinking and no operations, the question is retried once automatically. -- In an arm with analysis tools off, Copilot doesn't see the analysis tools or the analysis card when building the graph, and a graph that still binds analysis tools is sent back to be fixed; workflow questions (which test a pinned version of a published workflow) build no graph and aren't affected. Analysis tools on and off count as different variants, and a comparison with the previous evaluation shows "Analysis tools: on → off". +- In an arm with analysis tools off, Copilot doesn't see the analysis tools or the analysis card when building the graph, and a graph that still binds analysis tools is sent back to be fixed; in an arm with ontology penetration off, Copilot doesn't see `ontology_neighbors`, `source_health`, or cross-source ontology neighbor hints, and any graph binding those tools is likewise sent back to be fixed. Workflow questions (which test a pinned version of a published workflow) build no graph and aren't affected. On and off count as different variants, and comparisons with a previous evaluation report "Analysis tools: on -> off" or "Ontology penetration: on -> off". +- Cross-source diagnostic suites can declare `investigation` expectations (`require_source_health`, `min_ontology_hops`, `diagnosis_stage`) alongside `reconcile` and `cochange` verdict expectations; the repository includes the deterministic three-source manufacturing fixture `tests.fixtures.acceptance.multi_source_ontology` and `tests/fixtures/eval/ontology_suite.json`. - Concurrency, per-question time limits, and per-evaluation and daily spending all have caps, set under Settings → Preferences → Evaluation. Evaluation spending is tallied separately. - A question's time limit doesn't include time spent queuing. Under full load, evaluations queue behind Ask Data (see [Run concurrency](postgresql-and-scaling.md#run-concurrency)). - An evaluation can be stopped, and you can retry only the unfinished questions. A service restart marks it interrupted, and it doesn't resume by itself. @@ -128,3 +129,10 @@ After a new version of a governed caliber is published, the system looks up, in Four statistics are computed live by `GET /api/ledger/stats`: equivalence hits, reconciliation, question repetition, and recall (E1–E4). The Caliber hits & repetition tab on the evaluation page plots their trends. Evaluations, caliber reconciliations, and caliber recalls are runs the system starts on someone's behalf; they are left out of usage statistics, and the Records page doesn't list them by default. + +### Metric ontology topology + +Each caliber detail page includes a collapsible Metric Ontology and Cross-Source Lineage panel: + +- **Three link kinds and DAG validation**: metrics can declare `factor` links (validated as a directed acyclic graph whenever links are saved or change-request patches are applied), `reconciles_with` mirror links, and `upstream_driver` links, while backing physical table and column lineage is derived automatically from caliber card expressions. +- **Draft extraction and topology review**: drafting calibers from documentation emits candidate links as `proposed`; maintainers can inspect the interactive one-hop SVG topology, confirm or reject `proposed` links, or submit `/links` change requests so confirmed links become active for cross-source Ask Data penetration upon publication. diff --git a/docs/en/workflows.md b/docs/en/workflows.md index 90fe53de..82645237 100644 --- a/docs/en/workflows.md +++ b/docs/en/workflows.md @@ -40,7 +40,7 @@ When motion is turned off at the system level (`prefers-reduced-motion`), the li ### Built-in templates -There are 11 built-in templates, from Minimal Q&A to Anomaly Analysis (Traceable). They run as they are and also serve as executable documentation of how each kind of node is used. Templates 9, Traceable Weekly Report, and 11, Anomaly Analysis (Traceable), can be published at the governed level as they are: the first demonstrates caliber cards and issuance by citation; the second demonstrates the analysis card, which takes two queries, judges whether this week's change is within the usual fluctuation and which region it mainly came from, and leaves the report to cite only the verdict phrases (see [Analysis](analysis.md#analysis-cards)). +There are 12 built-in templates, from Minimal Q&A to Cross-Source Metric Anomaly and Reconciliation Diagnosis. They run as they are and also serve as executable documentation of how each kind of node is used. Templates 9, Traceable Weekly Report, 11, Anomaly Analysis (Traceable), and 12, Cross-Source Metric Anomaly and Reconciliation Diagnosis, can be published at the governed level as they are: 9 demonstrates caliber cards and issuance by citation, 11 demonstrates the analysis card, and 12 demonstrates health-first source checks, cross-source reconciliation, slice localization, and confirmed ontology penetration (see [Analysis](analysis.md#analysis-cards)). ## Node types diff --git a/docs/zh-CN/analysis.md b/docs/zh-CN/analysis.md index 9c8a0224..413ace25 100644 --- a/docs/zh-CN/analysis.md +++ b/docs/zh-CN/analysis.md @@ -81,6 +81,14 @@ 变化拆解给的是两份查询时,先自动做一次可比性检查;波动基线、趋势判断和单份查询的变化拆解看本期齐不齐时,用的是其中「整期」那一项。口径卡里一个指标用到两份同形、只差日期的查询(本周对上周)时,也自动做一次,结果挂在指标上(见[口径卡](evidence.md#口径卡))。 +### 跨源对账与伴随异动 + +在五种单源分析之外,跨源本体穿透提供两项跨指标确定性算子与一项数据源健康探针: + +- **跨源对账(`reconcile`)**:核对互为 `reconciles_with` 镜像的两套口径或两份查询按对齐键逐行的差额。支持 `scale` 量纲换算(如千瓦时与兆瓦时换算 `1000`)与绝对/相对容差,产出 `aligned`(对账一致)、`diverged`(对账偏离,点名超差实体段)或 `missing_counterpart`(单边缺失)。 +- **伴随异动(`cochange`)**:核对主指标与 `upstream_driver` 上游指标在同一时间序列与滞后窗口(`lag_periods` 为 `0` 至 `3` 期)上是否同步超出稳健波动基线(中位数与中位绝对偏差),并给出 Spearman 秩相关描述量,产出 `co_anomalous`(同期同步异动)、`target_normal`(上游平稳,排除该上游驱动)或 `opposite_move`。判定语与分析说法核对强制把 `cochange` 限定为**统计同步异动**,没有知识库明确规则依据时严禁写成「导致 / 引起 / 造成」。 +- **数据源健康核查(`source_health`)**:只读检查目标数据源或口径底层物理表的新鲜度断更(`date_stalled`)、日期断档(`date_gap`)、近期行数骤降(`volume_drop`)及目录外新增编码(`codes_new`),封存为 `H1`、`H2`…… 工件,报告可用 `[[h:H1]]` 与 `[[see:H1]]` 引用并在证据抽屉复核。 + ## 算不了的时候 算不了不让 Agent、节点失败,记成一条结论,判定语写「波动基线没有做成:历史只有 5 期,至少要 8 期」这样的一句,进台账、能引用、能核对: diff --git a/docs/zh-CN/ask-data.md b/docs/zh-CN/ask-data.md index 1459c2f8..81123d72 100644 --- a/docs/zh-CN/ask-data.md +++ b/docs/zh-CN/ask-data.md @@ -36,6 +36,14 @@ - 助手自查时按一张确定的词表认问题是不是分析类,只收明确的问法。是分析类、查库的 agent 却没绑分析工具时,交回助手改一轮;改过一轮仍没绑的照常运行,留一条提醒。 - 分析没做成(历史不够、本期没过完……)、判断词重写后仍没挂对的,复核只写一句说明,不自动重来(见[产出复核](#产出复核))。 +### 跨源本体穿透与异常升级 + +当指标触发契约越界、查询或指标无数据、跨源对账偏离或关联源健康异常时,问数据支持按已确认的业务本体关系跨数据源排查: + +- **三段式诊断纪律**:Agent 先调用 `ontology_neighbors` 查看目标口径已确认的一跳关联指标与标准实体桥,并用 `source_health` 核查外部源表是否断更、断档、行数骤降或出现新增未识别编码;若源表健康或跨源对账(`analysis_reconcile`)已检出故障,结论直接引用 `[[h:H1]]` 或 `[[a:A1]]` 早停,不在脏数据上强拆业务维度。源健康通过后再做同源维度定位,并把异常切片经 `caliber_query`(参数由标准实体确定性翻译)穿透到邻居口径做伴随异动检验(`analysis_cochange`)。 +- **异常排查升级(默认一键提示)**:简单取数轮次命中硬异常信号时,默认不额外重跑,而是在本轮复核操作区展示「指标触发异常,沿本体排查关联数据源」按钮(发起 `mode: "escalate"` 重试);也可在「设置 → 偏好设置 → 问数异常跨源排查」切为自动升级,最多自动追加 1 次跨源排查重试。 +- **状态与角色双门禁**:运行期自动穿透只走 `confirmed` / `verified` 状态的本体关系与标准实体绑定,`proposed` 候选不参与自动穿透;普通使用者只看得到、调得动其已授权应用固定版本的口径邻居,不会暴露未授权口径或底层物理表列。 + ## 产出复核 运行结束后,规则先扫一遍事件流,发现异常才调用模型复核。复核可以重组答案,但**不得引入原答案里没有的数字**。 diff --git a/docs/zh-CN/data-catalog.md b/docs/zh-CN/data-catalog.md index 4cd5eccd..7c612208 100644 --- a/docs/zh-CN/data-catalog.md +++ b/docs/zh-CN/data-catalog.md @@ -196,3 +196,19 @@ - 选步骤(探查结构、剖析需要的表、取值观察,可多选)和低峰时段,存成一条目标为这个数据源的定时任务。缺省没有。 - 和起草、剖析在同一个数据源上排队;没执行的步骤照实记原因。 - 这类定时任务不收 Webhook(回 422),通知走「设置 → 通知」的渠道订阅。 + +## 标准业务实体桥 + +不同业务库常对同一类对象使用不同表名、列名与编码前缀(例如车间库的产线码 `L1` 与设备主数据里的 `EQ-L1`)。数据目录页顶部提供「标准实体」(`?view=entities`)入口,统一登记跨源标准业务实体(`CanonicalEntity`): + +- **双栏治理**:左侧管理标准实体标识(如 `prod_line`)、名称与状态;右侧维护该实体在各数据源物理表列上的绑定(`bindings`)、口径入口参数映射(`caliber_params`)与跨源编码字典(`members`)。 +- **候选审阅与运行期门禁**:文档自动起草或协作者提交的跨源映射可先标为待确认(`proposed`),由维护者在「标准实体」页逐条确认或驳回;只有已确认(`confirmed` / `verified`)的绑定和参数映射才会参与问数运行期的跨源自动翻译(`align_caliber_inputs`)与助手查看时的实体桥提示。 +- **口径语义引用**:在口径详情的问数语义配置中,可直接为维度选择已登记的 `entity_key`,避免各口径重复手填跨库键值映射。 + +### Agent 辅助维护与业务文档联动 + +在「标准实体」页,除了手工表单编辑,还可以通过交互式助手和后台扫描维护跨源实体: + +- **实体助手**:点击页顶「实体助手」展开右侧对话抽屉(`POST /api/ontology/entities/assistant`)。默认只将当前进入的数据源纳入分析范围(避免混入其他独立业务域的表和口径),需要跨库对齐时可在抽屉顶部点「跨源选择」按需勾选关联库。助手可在选定源内读取数据目录与口径参数(`inspect_sources`)、执行脱敏只读查询核对真实枚举值(`run_query`)、检索挂载的业务文档(`read_document`),并输出结构化变更提案(`propose_entity_changes`)。提案不会自动落库,维护者可在抽屉中逐条保留或移出,点击「保存修改」后经乐观锁校验(`POST /api/ontology/entities/apply-patch`)以 `confirmed` 状态生效。 +- **扫描发现候选实体**:点击页顶「扫描发现候选实体」(`POST /api/ontology/discovery-jobs`),默认勾选当前数据源(支持按需多选同域数据源),后台任务会跨所选数据源、关联口径与文档自动识别同义主键、外键与编码映射。扫描产出的绑定与口径参数一律记为 `proposed`(来源 `ai`),绝不覆盖人工已确认或已驳回项,也不会直接参与线上问数穿透,须经人工审阅确认后生效。 +- **业务文档与主数据对照表附件**:在「实体助手」与「扫描发现候选实体」弹窗中,均可直接上传 `.md`、`.docx`、`.pdf`、`.xlsx`、`.csv` 等业务制度或跨系统编码对照表(`POST /api/ontology/entities/attachments`),也可勾选已有知识库文档。上传时可按需勾选「同时存入知识库供后续复用」(`save_to_kb`)并指定知识库集合,一次上传即可同时服务实体对齐与后续问数检索。 diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index 3e0c217c..14201cd8 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -122,7 +122,7 @@ python scripts/fake-erp.py --port 8765 ## 前端检查 ```bash -# 43 项,默认 8 道并行。连 5273 / 8000,先起 ./scripts/dev.sh +# 45 项,默认 8 道并行。连 5273 / 8000,先起 ./scripts/dev.sh node scripts/check-all.mjs # 另起 2 套只给检查用的「后端 + vite」,各用一份数据拷贝,约 6.5 分钟;边改代码边跑也不被打断 CHECK_DATA_SRC=<数据目录> node scripts/check-all.mjs --stacks 2 --lanes 12 @@ -135,7 +135,7 @@ node scripts/check-all.mjs evidence publish - `scripts/e2e-check.mjs` 真发起一次运行(Mock,不花钱),会在库里留下记录,所以不在 check-all 里。 - `scripts/check-auth.mjs`(登录、按角色收起的导航、401 跳登录)要另起一套开着本地账号登录的服务单独跑,也不在 check-all 里。 -`check-all` 的 43 项按 `scripts/check-all.mjs` 里 `ORDER` 的顺序排: +`check-all` 的 45 项按 `scripts/check-all.mjs` 里 `ORDER` 的顺序排: | 类别 | 检查 | |---|---| @@ -144,7 +144,7 @@ node scripts/check-all.mjs evidence publish | 外壳、回答流与运行态 | `shell` `stream` `evidence`(可点击证据)`run-states`(节点卡)`canvas-fx`(画布表层) | | 各页面 | `studio` `publish`(发布前检查与自动修复)`chat` `runs` `manage` `versions`(上传表格的版本)`catalog`(数据目录)`catalog-loop`(表助手、审阅队列、导出导入)`catalog-profile`(数据剖析的逐表任务)`catalog-changes`(变化、表详情的变化一节、定时维护、后台任务条)`ui`(端到端,连真数据) | | 复核套件与导出 | `schedules`(定时任务)`compare`(运行对比)`verify`(双盲复算、反方审稿)`inquiry`(审批质询)`challenge`(反方审稿)`bundle`(可验证报告)`whatif`(数字推演)`report-export`(报告导出) | -| 评测与口径账本 | `evals`(题集、加题、发起与进度、结果、对比与 A/B、口径命中与重复度)`ledger`(证据里的「口径」一步、轮次摘要、出具与对账、可沉淀的问题) | +| 评测与口径账本 | `evals`(题集、加题、发起与进度、结果、对比与 A/B、口径命中与重复度)`ledger`(证据里的「口径」一步、轮次摘要、出具与对账、可沉淀的问题)`caliber-drafts`(口径草稿工作台、增量重导入与一句话改口径)`ontology`(标准业务实体、口径本体拓扑、源健康证据链、异常升级与本体穿透归因) | | 应用平台 | `apps`(应用页、印章、点数字看出处、入口校验、实例页)`inbox`(会签进度、超时、动作确认的哈希卡、核实)`app-editor`(应用编辑、派生、检查、发布时选处置、助手)`capabilities`(能力、端点、身份、通知、审计)`access-keys`(访问密钥)`share`(分享链接与 /s 页)`blueprint`(新建应用、蓝图卡片、试运行、发布摘要)`personal`(个人应用)`records`(记录列表)`files`(文件控件) | ### 三层验证的分工 diff --git a/docs/zh-CN/evaluation-and-ledger.md b/docs/zh-CN/evaluation-and-ledger.md index d1028987..28923b2a 100644 --- a/docs/zh-CN/evaluation-and-ledger.md +++ b/docs/zh-CN/evaluation-and-ledger.md @@ -31,12 +31,13 @@ ### 发起评测 -1. 选变体:助手模型、写作模型、裁判开关、目录(当前 / 快照 / 只用已核实的 / 关)、分析工具(开 / 关,缺省开)、重复几次。 -2. 看预估花费,确认发起。「目录贡献」预设一次跑「当前 vs 关」,「分析工具贡献」预设一次跑「分析工具开 vs 关」。 +1. 选变体:助手模型、写作模型、裁判开关、目录(当前 / 快照 / 只用已核实的 / 关)、分析工具(开 / 关,缺省开)、本体穿透(开 / 关,缺省开)、重复几次。 +2. 看预估花费,确认发起。「目录贡献」预设一次跑「当前 vs 关」,「分析工具贡献」预设一次跑「分析工具开 vs 关」,「本体穿透贡献」预设一次跑「本体穿透开 vs 关」。 - 评测在后台跑,每题怎么走和用户在问数据里拿到的一样(建图、运行、复核)。停在审批上的不代批,照实记。 - 助手只给了思考、一个操作都没给时,自动重来一次。 -- 分析工具关掉的那一臂,助手建图时看不到分析工具和分析卡,图里还绑着分析工具的会被挡回去改;工作流题(考一个已发布工作流的固定版本)不建图,不受这一项影响。分析工具开、关不同算不同的变体,和上一次比时写「分析工具:开 → 关」。 +- 分析工具关掉的那一臂,助手建图时看不到分析工具和分析卡,图里还绑着分析工具的会被挡回去改;本体穿透关掉的那一臂,助手看不到 `ontology_neighbors`、`source_health` 及跨源本体邻居提示,绑定了本体工具的同样会被挡回去改。工作流题(考一个已发布工作流的固定版本)不建图,不受这两项影响。开关不同算不同的变体,和上一次比时分别标出「分析工具:开 → 关」「本体穿透:开 → 关」。 +- 跨源诊断题可配置调查过程期望(`investigation`:是否先核查数据源健康 `require_source_health`、最少本体跳数 `min_ontology_hops`、目标诊断阶段 `diagnosis_stage`)以及 `reconcile` / `cochange` 判定类期望;仓库附带三源制造验收库生成器 `tests.fixtures.acceptance.multi_source_ontology` 与题集 `tests/fixtures/eval/ontology_suite.json`。 - 并发、每题时限、单次和每日金额都有上限,在「设置 → 偏好设置 → 评测」里改。评测的花费单独记账。 - 每题的时限不算排队的时间。满载时评测会排在问数据后面(见[运行并发](postgresql-and-scaling.md#运行并发))。 - 能停,能只重试没做完的题。服务重启时标成中断,不会自己续跑。 @@ -135,3 +136,10 @@ 四项统计由 `GET /api/ledger/stats` 现算:等价命中、对账、问题重复度、召回(E1–E4)。评测页的「口径命中与重复度」页签画趋势。 评测、口径对账、口径召回是系统代为发起的运行,不进使用统计,记录页默认不列。 + +### 指标本体拓扑 + +口径详情页提供按需展开的「指标本体与跨源血缘」面板: + +- **三种本体边与有向无环校验**:指标间支持声明 `factor`(构成因子,保存或合并修改单时自动做有向无环校验,防循环依赖)、`reconciles_with`(跨源对账镜像)与 `upstream_driver`(上游业务驱动),同时自动反解口径卡底层表达式引用的物理表列血缘。 +- **草稿起草与拓扑审阅**:从业务文档自动抽取口径草稿时,识别到的指标关系以 `proposed` 候选写入;维护者可在本体面板预览一跳 SVG 拓扑、将 `proposed` 关系确认为 `confirmed`(或驳回),也可通过 `/links` 变更单补充新关系,发布后供问数跨源穿透使用。 diff --git a/docs/zh-CN/workflows.md b/docs/zh-CN/workflows.md index 669effcd..6d2e7631 100644 --- a/docs/zh-CN/workflows.md +++ b/docs/zh-CN/workflows.md @@ -40,7 +40,7 @@ ### 内置模板 -内置 11 个模板,从「最小问答」到「异动分析(可追溯)」。它们可以直接运行,也是各类节点用法的可执行文档。「⑨ 可追溯周报」和「⑪ 异动分析(可追溯)」拿来就能按受管级别发布:前者示范口径卡和按引用出具,后者示范分析卡——两次查询取数,分析卡判这一周的变化在不在常规波动范围内、主要来自哪个地区,报告只引用判定语(见[分析能力](analysis.md#分析卡))。 +内置 12 个模板,从「最小问答」到「跨源指标异动与对账诊断」。它们可以直接运行,也是各类节点用法的可执行文档。「⑨ 可追溯周报」「⑪ 异动分析(可追溯)」和「⑫ 跨源指标异动与对账诊断」拿来就能按受管级别发布:⑨ 示范口径卡和按引用出具,⑪ 示范分析卡,⑫ 示范先核数据源健康与跨源对账、再做同源拆解与已确认本体穿透的诊断报告(见[分析能力](analysis.md#分析卡))。 ## 节点类型 diff --git a/frontend/src/api/chatTurns.ts b/frontend/src/api/chatTurns.ts index 34bf8c3d..fe45c7ba 100644 --- a/frontend/src/api/chatTurns.ts +++ b/frontend/src/api/chatTurns.ts @@ -13,7 +13,68 @@ import type { ConversationTurn } from '../types' import { ApiError, BASE, NETWORK_MESSAGE, actorHeader, failure, get, parseBody, post, report } from './http' /** 发起一轮的方式(服务端 app/chat/job.MODES) */ -export type ChatTurnMode = 'ask' | 'retry' | 'rerun' | 'max_steps' | 'run' | 'continue' | 'resume' +export type ChatTurnMode = 'ask' | 'retry' | 'rerun' | 'max_steps' | 'run' | 'continue' | 'resume' | 'escalate' + +/** 问数模式:fast 为快速直查(语义预命中 + 单 Agent 直查),deep 为深度分析(搭工作流 + 报告 + 复核) */ +export type ChatDepth = 'fast' | 'deep' + +export interface GroundingMetricHit { + id: string + key: string + name: string + unit?: string + datasource_id?: string + datasource_name?: string + table_name?: string + sql_expression?: string + date_column?: string + aggregation_type?: string + match_reason?: string +} + +export interface GroundingEntityHit { + entity_id: string + entity_key: string + label: string + entity_type?: string + matched_member?: { + member_id?: string + canonical_value?: string + canonical_label?: string + matched_term?: string + target_codes?: Record + } | null + bound_columns?: { source_id: string; source_name: string; table_name: string; column_name: string }[] +} + +export interface GroundingTableHit { + datasource_id: string + datasource_name: string + table_name: string + label?: string + grain?: string + business_date?: string + valid_filter?: string + reason?: string +} + +export interface GroundingGuardrail { + kind: 'business_date' | 'valid_filter' | 'stock_columns' | string + table?: string + column?: string + columns?: string[] + filter?: string + note?: string +} + +export interface GroundingSummary { + elapsed_ms: number + narrowed_sources?: { id: string; name: string }[] + metrics?: GroundingMetricHit[] + entities?: GroundingEntityHit[] + tables?: GroundingTableHit[] + guardrails?: GroundingGuardrail[] +} export interface ChatTurnStart { conversation_id: string @@ -23,6 +84,7 @@ export interface ChatTurnStart { retry_of?: string mode?: ChatTurnMode max_steps?: number + depth?: ChatDepth } /** 事件日志里的一条(服务端 app/chat/job.py 的模块说明列了各种 type) */ diff --git a/frontend/src/pages/ChatPage.tsx b/frontend/src/pages/ChatPage.tsx index 3f4c1a33..22fbc8a1 100644 --- a/frontend/src/pages/ChatPage.tsx +++ b/frontend/src/pages/ChatPage.tsx @@ -1,10 +1,11 @@ import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode, type RefObject } from 'react' -import { Link, useNavigate, useParams } from 'react-router-dom' +import { Link, useLocation, useNavigate, useParams } from 'react-router-dom' import { - AlertCircle, ArrowRight, BookOpen, Check, ChevronDown, ChevronRight, CloudOff, Database, History, LayoutGrid, ListTree, - MessageSquare, PenLine, Play, RotateCw, Settings2, StepForward, Trash2, Wrench, + AlertCircle, ArrowRight, BookOpen, Check, ChevronDown, ChevronRight, CloudOff, Database, History, Layers, LayoutGrid, ListTree, + MessageSquare, PenLine, Play, RotateCw, Settings2, ShieldCheck, StepForward, Tag, Trash2, Wrench, Zap, } from 'lucide-react' import clsx from 'clsx' +import type { ChatDepth, GroundingSummary } from '../api/chatTurns' import { ApiError, api } from '../api/client' import { ApprovalCard } from '../run/RunPanel' import { AssistantStream, type StreamTurn, type TurnFailure } from '../run/AssistantStream' @@ -47,7 +48,8 @@ import { * dense 一个开关。两边各写一套的话,同一次运行在两个页面会讲出不同的故事。 */ export function ChatPage() { - const { ask, stop, load, hydrate, recheck, setScope } = useChat() + const { ask, stop, load, hydrate, recheck, setScope, setDepth } = useChat() + const depth = useChat((s) => s.depth) const { conversationId } = useParams() const navigate = useNavigate() const currentId = useConversations((s) => s.currentId) @@ -219,10 +221,16 @@ export function ChatPage() { // 库列表还在取、或者没取回来时也挂着:从上一问接过来的范围照样会发出去,得看得见。 // 没东西可摆时它自己不画 - const picker = usable.length > 0 || scope.length > 0 || sources.state !== 'ready' + const scopePicker = usable.length > 0 || scope.length > 0 || sources.state !== 'ready' ? - : undefined + : null + const picker = ( +
+ + {scopePicker} +
+ ) const dock = (
@@ -561,9 +569,11 @@ function TurnExtras({ turnId, readOnly }: { readOnly: boolean }) { const conversationId = useConversations((s) => s.currentId) - const turn = useChat((s) => (conversationId ? s.byConversation[conversationId]?.find((t) => t.id === turnId) : undefined)) + const turns = useChat((s) => (conversationId ? s.byConversation[conversationId] : undefined)) + const turn = turns?.find((t) => t.id === turnId) + const isLast = turns?.[turns.length - 1]?.id === turnId const approvals = useCatalog((s) => s.approvals) - const { reattach, runNow, toggleSteps } = useChat.getState() + const { reattach, runNow, toggleSteps, retryTurn, ask } = useChat.getState() const busy = useChat((s) => (conversationId ? isBusy(s.byConversation[conversationId]) : false)) // 做成应用进蓝图:搭建者建共享的;使用者在管理员开了个人应用时建个人的,都不是就没有这个按钮 const makeScope = useCreateScope() @@ -572,12 +582,21 @@ function TurnExtras({ turnId, readOnly }: { const pending = runId ? approvals.filter((a) => a.run_id === runId && a.status === 'pending') : [] const canSteps = !!turn.restored && !!runId && !BUSY.has(turn.phase) const scoped = !!turn.scope?.length + const hasGrounding = !!turn.grounding && ( + (turn.grounding.metrics?.length ?? 0) > 0 + || (turn.grounding.entities?.length ?? 0) > 0 + || (turn.grounding.tables?.length ?? 0) > 0 + || (turn.grounding.guardrails?.length ?? 0) > 0 + ) // 回答成功、有运行的轮次可以做成应用:带着这次运行进蓝图 const canApp = !!runId && turn.phase === 'done' && !readOnly && !!makeScope + // 快速直查完成的轮次支持一键升级为深度分析(搭建多步工作流 + 撰写报告 + 复核) + const canUpgradeDeep = turn.phase === 'done' && turn.depth === 'fast' && !turn.asked && !readOnly - if (!pending.length && !turn.pendingRun && !canSteps && !scoped && !canApp) return null + if (!pending.length && !turn.pendingRun && !canSteps && !scoped && !hasGrounding && !canApp && !canUpgradeDeep) return null return ( <> + {hasGrounding && } {/* 和「没查库」一样,写在结论前面:这个答案只看了这几个库 */} {scoped && (
@@ -585,7 +604,7 @@ function TurnExtras({ turnId, readOnly }: { 本轮只查 {turn.scope!.map((s) => s.name).join('、')}
)} - {(turn.pendingRun || canSteps || canApp) && ( + {(turn.pendingRun || canSteps || canApp || canUpgradeDeep) && (
{turn.pendingRun && ( + )} {canApp && }
)} @@ -699,14 +731,42 @@ function Remedies({ conversationId, turnId, last, onRephrase, readOnly }: { setResuming(false) } } - const again = (opts?: { maxSteps?: number; rerun?: boolean; scope?: ScopeSource[] }) => { + const again = (opts?: { maxSteps?: number; rerun?: boolean; escalate?: boolean; scope?: ScopeSource[] }) => { if (last) retryTurn(conversationId, turn.id, opts) else if (ask(conversationId, turn.question, opts?.scope ? { scope: opts.scope } : undefined)) { toast.info('已在对话末尾用同一问题重新提问') } } + const escalation = turn.phase === 'done' + ? (() => { + const esc = (turn.review ?? turn.reviewRaw)?.anomaly_escalation + return esc?.available && !esc.auto_escalate ? esc : null + })() + : null const buttons: ReactNode[] = [] + if (escalation) { + buttons.push( + , + ) + } if (kind === 'unknown') { buttons.push( + +
+ ) +} + +function GroundingStrip({ grounding, depth }: { grounding: GroundingSummary; depth?: ChatDepth }) { + const metrics = grounding.metrics ?? [] + const entities = grounding.entities ?? [] + const tables = grounding.tables ?? [] + const guardrails = grounding.guardrails ?? [] + const msText = typeof grounding.elapsed_ms === 'number' + ? `${Math.max(1, Math.round(grounding.elapsed_ms))} ms` + : null + const guardrailNotes = guardrails.map((g) => g.note || g.filter || g.column || g.kind).filter(Boolean).join('\n') + + return ( +
+ + + {depth === 'deep' ? '深度分析预命中' : '语义预命中'} + {msText && · {msText}} + + {metrics.map((m) => ( + + + 指标:{m.name}{m.unit ? `(${m.unit})` : ''} + + ))} + {entities.map((e) => { + const memberLabel = e.matched_member?.canonical_label || e.matched_member?.canonical_value + const codePairs = e.matched_member?.target_codes + ? Object.entries(e.matched_member.target_codes).map(([src, codes]) => `${src} → ${codes.join(' / ')}`).join(';') + : '' + return ( + + 业务实体:{memberLabel ? `${e.label} · ${memberLabel}` : e.label} + + ) + })} + {tables.slice(0, 4).map((t) => ( + + + {t.label ? `${t.table_name}(${t.label})` : t.table_name} + + ))} + {tables.length > 4 && 等 {tables.length} 张目录表} + {guardrails.length > 0 && ( + + + 目录防错 {guardrails.length} 项 + + )} +
+ ) +} + /** * 这一问查哪些库,挂在输入框左边。默认不限:它自己挑。限定之后 Copilot 只拿得到这几个 * 库的工具,搭出来的流程要是查到别的库,自查就不让它跑。 @@ -1293,7 +1454,8 @@ interface SourcesState { state: 'loading' | 'ready' | 'error'; list: Source[] } function useDataSources(): SourcesState { // 列表是全站共用的那份;旧了(半分钟以上)进页面时后台重取,别的标签页、别人刚加的库 // 不用整页刷新就能出现在范围、例句里 - const { list, state: listState } = useDatasources() + const { key: routeKey } = useLocation() + const { list, state: listState } = useDatasources({ refreshKey: routeKey }) const [tables, setTables] = useState>({}) // 开了登录的使用者(D-c)只拿得到数据源的名字和说明,表结构接口只给搭建者:例句按名字和说明造,不去取表名 const builder = useAtLeast('builder') diff --git a/frontend/src/store/chat.ts b/frontend/src/store/chat.ts index d346df58..41a6feae 100644 --- a/frontend/src/store/chat.ts +++ b/frontend/src/store/chat.ts @@ -1,7 +1,9 @@ import { create } from 'zustand' import { ANALYSIS_TEXT, analysisMethodLabel, analysisToolOp } from '../lib/termsAnalysis' import { ApiError, api, streamRun } from '../api/client' -import { streamChatTurn, type ChatTurnEvent, type ChatTurnStart } from '../api/chatTurns' +import { + streamChatTurn, type ChatDepth, type ChatTurnEvent, type ChatTurnStart, type GroundingSummary, +} from '../api/chatTurns' import type { CopilotOp, FixKind, RunFinal } from '../run/decode' import { copilotContext, copilotLook, decodeRun } from '../run/decode' import { CHAT_BLUEPRINT_TEXT, CHAT_RETRY_TEXT, LEDGER_TEXT, LOOK_TEXT, REJECTED_TEXT } from '../lib/terms' @@ -191,6 +193,10 @@ export interface TurnMeta { at?: number /** 这一轮的花费:助手建图、运行、复核各一份(next-round 细案 01 做法 3),见 TurnUsage */ usage?: TurnUsage + /** 问数模式:fast 为快速直查,deep 为深度分析 */ + depth?: ChatDepth + /** 语义预命中摘要(指标、业务实体、数据目录表、防错规则) */ + grounding?: GroundingSummary } /** @@ -304,6 +310,10 @@ export interface ChatTurn { asked?: string /** 这一轮在服务端的任务(从库里恢复时带来的):进行中的从它的 attempt_seq 接着播 */ job?: ChatTurnJob | null + /** 问数模式:fast 为快速直查,deep 为深度分析 */ + depth?: ChatDepth + /** 语义预命中摘要 */ + grounding?: GroundingSummary } export type LoadState = 'loading' | 'ready' | 'error' @@ -326,6 +336,9 @@ interface ChatState { */ scopes: Record setScope: (key: string, scope: ScopeSource[]) => void + /** 默认问数模式:快速直查(fast)或深度分析(deep) */ + depth: ChatDepth + setDepth: (depth: ChatDepth) => void turnsOf: (conversationId: string | null) => ChatTurn[] /** force:已经取回来过也再取一次(重连后、点重试时) */ @@ -334,7 +347,7 @@ interface ChatState { * 发出去了返回 true。会话还在加载或加载失败、或者正忙时不发。 * scope 不给就用这个会话眼下的范围 */ - ask: (conversationId: string, question: string, opts?: { scope?: ScopeSource[] }) => boolean + ask: (conversationId: string, question: string, opts?: { scope?: ScopeSource[]; depth?: ChatDepth }) => boolean /** 只停这个会话自己正在跑的那一轮(服务端那一轮连同它的运行一起停) */ stop: (conversationId: string) => void /** 审批完成后重新接上运行的实时流 */ @@ -349,11 +362,12 @@ interface ChatState { * 用户主动重试这一轮:上一次由服务端折叠留档,新的一次接在同一轮里。 * maxSteps:把图里 agent 的步数上限调到这个值,原图重跑(「放宽步数重跑」); * rerun:原图原样重跑(取消了、中断了的那种,不需要改); - * scope:换一个数据源范围重来(限定的库不在了),不给就沿用这一轮的 + * scope:换一个数据源范围重来(限定的库不在了),不给就沿用这一轮的; + * depth:切换快速直查与深度分析重跑 */ retryTurn: ( conversationId: string, turnId: string, - opts?: { maxSteps?: number; rerun?: boolean; scope?: ScopeSource[] }, + opts?: { maxSteps?: number; rerun?: boolean; escalate?: boolean; scope?: ScopeSource[]; depth?: ChatDepth }, ) => void /** 向后端核对一轮历史:真实状态、完整答案、档位;服务端还在跑的接着播。只做一次 */ hydrate: (conversationId: string, turnId: string) => Promise @@ -383,6 +397,7 @@ const PHASE_TEXT: Record = { /** 复核那一步的进度 */ const REVIEWING = '正在核对结果…' +const GROUNDING_TEXT = '正在匹配指标、业务实体与数据目录…' const EMPTY: ChatTurn[] = [] @@ -687,6 +702,7 @@ function rejectedOf(r: TurnMeta['rejected']): Rejected | null { /** 服务端还在跑的这一轮,它在哪一步 → 这一页的相位和进度 */ function livePhase(job: ChatTurnJob): { phase: Phase; status: string } { if (job.stage === 'waiting') return { phase: 'waiting', status: PHASE_TEXT.waiting } + if (job.stage === 'ground') return { phase: 'planning', status: GROUNDING_TEXT } if (job.stage === 'run') return { phase: 'running', status: PHASE_TEXT.running } if (job.stage === 'review') return { phase: 'running', status: REVIEWING } return { phase: 'planning', status: PHASE_TEXT.planning } @@ -777,6 +793,8 @@ function restoreTurn(t: ConversationTurn): ChatTurn { asked: meta?.asked && answer ? answer : undefined, usage: meta?.usage, job: t.job ?? null, + depth: meta?.depth, + grounding: meta?.grounding, } } @@ -849,8 +867,10 @@ export const useChat = create((set, get) => ({ loadState: {}, loadError: {}, scopes: {}, + depth: 'fast', setScope: (key, scope) => set((s) => ({ scopes: { ...s.scopes, [key]: scope } })), + setDepth: (depth) => set({ depth }), turnsOf: (conversationId) => (conversationId && get().byConversation[conversationId]) || EMPTY, @@ -929,16 +949,19 @@ export const useChat = create((set, get) => ({ const id = newId() const scope = opts?.scope ?? get().scopes[conversationId] ?? [] + const depth = opts?.depth ?? get().depth set((s) => ({ byConversation: { ...s.byConversation, [conversationId]: [ ...(s.byConversation[conversationId] ?? []), { - id, serverId: null, question, phase: 'planning', status: PHASE_TEXT.planning, + id, serverId: null, question, phase: 'planning', + status: depth === 'fast' ? GROUNDING_TEXT : PHASE_TEXT.planning, thinking: '', ops: [], events: [], graph: null, explanation: '', run: null, output: null, error: '', startedAt: Date.now(), lastSeq: 0, cancel: null, attempt: 0, scope: scope.length ? scope : undefined, + depth, }, ], }, @@ -947,7 +970,7 @@ export const useChat = create((set, get) => ({ })) useConversations.getState().touch(conversationId, question) void launchTurn(flowOf(conversationId, id), { - conversation_id: conversationId, question, + conversation_id: conversationId, question, depth, ...(scope.length ? { datasource_ids: scope.map((d) => d.id) } : {}), }) return true @@ -1010,19 +1033,30 @@ export const useChat = create((set, get) => ({ if (!turn || isBusy(turns) || inTrash(conversationId)) return turn.cancel?.() const flow = flowOf(conversationId, turnId) - const base = turn.graph && (turn.graph.nodes?.length ?? 0) > 0 - const mode = base && opts?.maxSteps ? 'max_steps' as const : base && opts?.rerun ? 'rerun' as const : 'retry' as const + const base = !opts?.depth && turn.graph && (turn.graph.nodes?.length ?? 0) > 0 + const mode = opts?.escalate ? 'escalate' as const + : base && opts?.maxSteps ? 'max_steps' as const + : base && opts?.rerun ? 'rerun' as const : 'retry' as const const scope = opts?.scope ?? turn.scope + const nextDepth = opts?.depth ?? turn.depth + const switchText = opts?.depth === 'deep' + ? '正在切换为深度分析并生成工作流…' + : opts?.depth === 'fast' + ? '正在切换为快速直查…' + : retryStatus(mode, opts?.maxSteps) // 先把相位摆出来;上一次怎么归档、这一次从哪开始,等服务端的 turn.attempt 来了照它重置 flow.patch(() => ({ - phase: mode === 'retry' ? 'planning' : 'running', status: retryStatus(mode, opts?.maxSteps), + phase: mode === 'retry' || mode === 'escalate' ? 'planning' : 'running', status: switchText, failure: null, error: '', pendingRun: false, hydrated: 'done', endedAt: undefined, cancel: null, startedAt: Date.now(), writing: null, scope: scope?.length ? scope : undefined, + ...(nextDepth ? { depth: nextDepth } : {}), + ...(opts?.depth ? { grounding: undefined } : {}), })) if (!turn.serverId) { // 发起那一下就没到服务端(这一轮在库里不存在):原样再问一次 void launchTurn(flow, { conversation_id: conversationId, question: turn.question, + ...(nextDepth ? { depth: nextDepth } : {}), ...(scope?.length ? { datasource_ids: scope.map((d) => d.id) } : {}), }) return @@ -1031,6 +1065,7 @@ export const useChat = create((set, get) => ({ conversation_id: conversationId, retry_of: turn.serverId, mode, ...(mode === 'max_steps' ? { max_steps: opts!.maxSteps } : {}), ...(opts?.scope ? { datasource_ids: opts.scope.map((d) => d.id) } : {}), + ...(opts?.depth ? { depth: opts.depth } : turn.depth && mode === 'retry' ? { depth: turn.depth } : {}), }) }, @@ -1152,8 +1187,9 @@ if (import.meta.env.DEV) { } /** 用户点重试时先摆出来的那一句(服务端的 turn.attempt 来了照它再说一遍) */ -function retryStatus(mode: 'retry' | 'rerun' | 'max_steps' | string, maxSteps?: number): string { +function retryStatus(mode: 'retry' | 'rerun' | 'max_steps' | 'escalate' | string, maxSteps?: number): string { return mode === 'max_steps' ? `正在将步数上限放宽到 ${maxSteps} 并重新运行…` + : mode === 'escalate' ? '正在沿本体排查关联数据源…' : mode === 'rerun' ? '正在重新运行本轮…' : mode === 'retry' ? '正在按原问题重新生成…' : mode === 'run' || mode === 'continue' || mode === 'resume' ? PHASE_TEXT.running @@ -1311,10 +1347,13 @@ function attemptReset(t: ChatTurn, d: Record, ts: number): Partial< startedAt, endedAt: undefined, writing: null, noQuery: false, restored: false, steps: undefined, } } + const nextDepth: ChatDepth | undefined = d.depth === 'fast' || d.depth === 'deep' ? d.depth : t.depth return { - phase: mode === 'ask' || mode === 'retry' ? 'planning' : 'running', - status: mode === 'ask' ? PHASE_TEXT.planning : retryStatus(mode, Number(d.max_steps) || undefined), + phase: mode === 'ask' || mode === 'retry' || mode === 'escalate' ? 'planning' : 'running', + status: mode === 'ask' ? (nextDepth === 'fast' ? GROUNDING_TEXT : PHASE_TEXT.planning) : retryStatus(mode, Number(d.max_steps) || undefined), attempts, scope, usage, + ...(nextDepth ? { depth: nextDepth } : {}), + grounding: undefined, ops: [], events: [], run: null, output: null, review: null, reviewRaw: null, rawOutput: null, failure: null, error: '', lastSeq: 0, final: undefined, rejected: null, runStatus: undefined, clipped: undefined, pendingRun: false, steps: undefined, @@ -1340,6 +1379,12 @@ function opPatch(t: ChatTurn, op: CopilotOp): Partial { // 查看进行中(looking)不是这一页的阶段:浮条直说「正在查看表结构…」 return { ops, status: op.phase === 'looking' ? LOOK_TEXT.running : PHASE_TEXT[(op.phase as Phase) ?? 'planning'] ?? '正在处理…' } + case 'grounding': + return { + ops, + grounding: op.grounding && typeof op.grounding === 'object' ? (op.grounding as GroundingSummary) : t.grounding, + status: '已完成语义预命中,正在查询…', + } case 'look': case 'context': { // 查看结束:浮条换成查看了什么 @@ -1408,6 +1453,8 @@ function endPatch(t: ChatTurn, d: Record): Partial { // 计时停在服务端记的那一刻(补交付的停在运行结束时) clipped: undefined, writing: null, endedAt: r.meta?.ms != null ? t.startedAt + r.meta.ms : Date.now(), job: row.job ?? null, + depth: r.depth ?? t.depth, + grounding: r.grounding ?? t.grounding, } } @@ -1458,6 +1505,8 @@ function play(flow: Flow, serverId: string, after: number) { // 补交付(运行早就跑完了)停在「正在核对」,不按实时运行画 if (t.phase === 'checking' && t.endedAt) return { turnSeq: e.seq, ...(stage === 'review' ? { runStatus: 'succeeded' } : {}) } switch (stage) { + case 'ground': + return { turnSeq: e.seq, phase: 'planning' as Phase, status: GROUNDING_TEXT } case 'build': return { turnSeq: e.seq, ...(t.phase === 'planning' || t.phase === 'building' ? {} : { phase: 'planning' as Phase }) } case 'run': @@ -1654,7 +1703,10 @@ function watch(flow: Flow, runId: string, after = 0): () => void { const op = analysisToolOp(tool) patch((t) => (t.phase !== 'running' ? {} : { status: tool.startsWith('db_query') ? '正在查询数据…' + : tool === 'metric_query' ? '正在按指标口径查询…' : tool.startsWith('db_schema') ? '正在读取数据结构…' + : tool === 'ontology_neighbors' ? '正在查询指标本体邻域…' + : tool === 'source_health' ? '正在核查数据源健康…' : op ? ANALYSIS_TEXT.step.running(analysisMethodLabel(op, d.args?.mode)) : tool ? `正在调用 ${tool}…` : '正在运行…', })) diff --git a/scripts/check-chat.mjs b/scripts/check-chat.mjs index ca9590ae..439e541d 100644 --- a/scripts/check-chat.mjs +++ b/scripts/check-chat.mjs @@ -1716,6 +1716,8 @@ for (const theme of THEMES) { const bodyAfter = await page.evaluate(() => Math.round(document.querySelector('[data-stream-scroll]')?.getBoundingClientRect().width ?? 0)) check('390 宽:抽屉打开时正文不被挤窄', bodyAfter === narrow.body, `${narrow.body} → ${bodyAfter}`) await page.screenshot({ path: `${SHOTS}/narrow-390-drawer-${theme}.png` }) + // 目录失败提示在窄屏会覆盖顶部会话;先按真实用户路径关闭提示,再验证抽屉选中交互。 + for (const close of await page.getByRole('button', { name: '关闭提示', exact: true }).all()) await close.click() await drawer.locator('div.group', { hasText: '会话 B' }).locator('button').first().click() await page.waitForURL(/\/chat\/c0idleb$/, { timeout: 5000 }).catch(() => {}) await page.waitForTimeout(300) @@ -3551,6 +3553,14 @@ for (const theme of THEMES) { `${log.sourceGets - getsBefore} 次`) check('别处刚加的库出现在首屏的标签里', await page.locator('[data-scope-chip="ds-new"]').waitFor({ timeout: 5000 }) .then(() => true, () => false)) + const freshGets = log.sourceGets + await page.locator('nav[aria-label="主导航"] a[href="/runs"]').click() + await page.waitForURL((u) => u.pathname.startsWith('/runs')) + await page.locator('nav[aria-label="主导航"] a[href^="/chat"]').first().click() + await page.waitForURL((u) => u.pathname.startsWith('/chat')) + await page.locator('[data-scope-chip="ds-new"]').waitFor({ timeout: 5000 }) + await page.waitForTimeout(300) + check('缓存仍新鲜时快速往返不重复取库列表', log.sourceGets === freshGets, `${log.sourceGets - freshGets} 次`) ctl.extraSource = false check('没有运行时报错', errors.length === 0, errors[0] ?? '') await ctx.close()