diff --git a/backend/app/analysis/contract.py b/backend/app/analysis/contract.py index cd7e9d1d..4212b817 100644 --- a/backend/app/analysis/contract.py +++ b/backend/app/analysis/contract.py @@ -397,6 +397,8 @@ class ScopeBlock(TypedDict, total=False): not_decomposed: list[str] | None # 候选维度里没拆过的叫法;None = 候选维度核对不了 note: str | None # 核对不了时的一句说明 tests: int # 这次做了几次差异检验 + corrected: bool | None # 检验校正过没有:只做了一次为 True(一次里比了多对的已按次数校正),不止一次为 + # False(几次之间没有校正),没做为 None #: 复算核对时不比的字段:hypothesis 是 agent 写的话,不是算出来的 diff --git a/backend/app/engine/analysis_claims.py b/backend/app/engine/analysis_claims.py new file mode 100644 index 00000000..36b46e93 --- /dev/null +++ b/backend/app/engine/analysis_claims.py @@ -0,0 +1,906 @@ +"""分析说法核对(docs/design/analysis-round/00-总方案.md §3.5,细案 01 §9):报告里的判断词要挂对应的分析结论,判定对得上。 + +「叙述层无算术」往前走一步:「主要来自华东」「超出常规波动」「持续上升」这类判定和数字一样由系统算、由系统渲染([[a:A3]]), +写作者只引用。写作者自己写了判断词的,这里确定地核对(不调模型,D6): + +1. **说法表**(LEXICONS,一处定义,带版本 LEXICON_VERSION):判断词分成来源、分散、抵消、结构、异常、新高新低、正常、 + 趋势、无趋势、差异、无差异、因果几类,每类要挂一种分析(op),判定要对得上(细案 01 §9.1)。只收强判断词,宁可漏报 + 不误报:「持续」要跟着涨跌(「持续关注」不算),「异常」后面接着订单、数据这类名词的是业务分类、前面是数据、系统的是 + 数据质量,都不算;「相当」只认句读前的(「相当于」「相当高」不算) +2. **否定**:判断词前 4 个字以内(跳过「出现」「明显」这类填充词)有「不、没有、没、并非、并不、未、无」的翻到反面类: + 「并未出现明显异常」是正常,「没有明显的上升趋势」是无趋势,「并非主要来自华东」要拆解、华东不在主要来源里; + 「不但」「不少」「无论」「未来」这类不是否定 +3. **怎么挂**:一句话的分析依据 = 句中的 [[a:]]、[[v:A…]]、[[table:A…]] 和句末 [[see:A…]](组装、复核时按重新解析的 + 引用算,见 evidence.verify_doc)。类要的 op 必须在依据里出现,几个里任一个对得上就算对;挂了算不了的结论算对不上 +4. **点名的段**:判断词所在分句里出现的结论结果表的维度值(全半角归一,两个字以上、不是纯数字)。来源类要判定说了主要 + 来源(driver、concentrated,比率拆解的 mix_driven、rate_driven),点名的段都在 subjects 里;拖累要那一段变化为负, + 拉动、带动为正(不在 subjects 里、但那一段的变化占总变化过半的也算拖累) +5. **来源和因果的分界**:句子挂了拆解、因果词所在分句点名的是这份结论的段或因子(「下降主要由华东造成」)→ 按来源核, + 这是记账意义上的「来自」;点名的不是(「由于促销结束导致下降」)→ 按因果核:同一句要有知识库原话([[q:]])或运行 + 输入([[i:]])作依据,或者写成推测(可能、或许、推测、待核实、不排除、疑似)。分句里已有来源一类判断词的,因果词 + 并进那一处核。原因说的是数据本身(「由于数据只到 10 月 16 日」「样本少」)的不算 +6. **不扫的地方**:知识库原话([[q:]] 片段)、系统渲染的判定语([[a:]] 片段)、别的引用渲染出来的字、标题、代码块、 + 表头;分析范围是文档的结构化字段(analysis_scope),本来就不在正文里 + +违规三种(CODES):analysis_claim_uncited(有判断词,依据里没有对应种类的分析结论)、analysis_claim_mismatch(挂了,判定、 +点名的段、方向对不上,含挂了算不了的结论)、causal_unsupported(因果词没有依据、也不是推测)。每条带:代码、判断词 +(text)、所在句子(context)、类(claim)、要的 op、这句挂的分析(analyses)、给人看的一句(message)和交回写作者的 +一句(for_model)。 + +报告文档记下按哪种处置、哪一版说法表核(DOC_FIELD:{"mode": check / strict, "lexicon": 1},参与内容哈希):只有带这一项 +的文档在复核时核这一项(verify),老文档复核结果不变;复核按文档记下的那一版说法表,说法表升了版老文档照旧。 + +整个模块是纯函数,不碰数据库、不调模型。 +""" +from __future__ import annotations + +import re +import unicodedata +from collections.abc import Iterable, Mapping +from dataclasses import dataclass, field +from decimal import Decimal, InvalidOperation +from typing import Any + +from app.analysis.contract import LEDGER_KIND, OP_LABELS, catalog_result, method_label +from app.engine.evidence import _Reason, _violation, iter_units + +#: 说法表的版本:改了判断词、类、绑定规则就升版本,老版本留在 LEXICONS 里给老文档复核用 +LEXICON_VERSION = 1 +#: 报告节点 analysis_claims 的取值里要核的两种(off 不核、文档里也不记) +MODES = ("check", "strict") +#: 报告文档里记下核对处置和说法表版本的字段 +DOC_FIELD = "analysis_claims" +UNCITED = "analysis_claim_uncited" +MISMATCH = "analysis_claim_mismatch" +CAUSAL = "causal_unsupported" +CODES = frozenset({UNCITED, MISMATCH, CAUSAL}) + +# -------------------------------------------------------------------------- +# 说法表 v1 +# -------------------------------------------------------------------------- + +#: 涨跌的说法。「扩大」「缩小」「收窄」不收:亏损扩大、差距缩小说不清是哪个方向 +_UP = "上升|增长|增加|提升|提高|上涨|攀升|走高|上扬|走强|回升|反弹|增多|上行|抬升|拉升" +_DOWN = "下降|下滑|减少|降低|下跌|走低|回落|走弱|萎缩|减弱|下行|下挫|走软|缩水" +_DIR = f"(?:{_UP}|{_DOWN})" +_UP_RE = re.compile(_UP) +_DOWN_RE = re.compile(_DOWN) +#: 分句的边界(顿号、冒号不算:「集中在华东、华北」「主要来自:华东」还是一句里的事) +_STOPS = ",,;;。!?!?\n" +_NOT_STOP = f"[^{_STOPS}]" + + +@dataclass(frozen=True) +class Claim: + """说法表的一类:判断词(words)、要挂的分析(op,结构变化另要 mode ratio)、判断词前有否定时翻到哪一类(flip,None: + 否定了就不核,宁可漏报)。negative:这一类的说法本身就是否定的写法(「并不异常」「没有明显趋势」),不再看前面的否定。 + 同一类可以有几条(key 相同):翻到这一类时用第一条。""" + + key: str + label: str + op: str | None + words: re.Pattern[str] + flip: str | None = None + mode: str | None = None + negative: bool = False + #: 「连续…上升」:另要末尾连续同向至少 3 期 + run: bool = False + + +@dataclass(frozen=True) +class Lexicon: + version: int + claims: tuple[Claim, ...] + #: 判断词本身带的方向(不看上下文):骤降是跌、激增是涨、拖累要那一段是跌 + intrinsic: tuple[tuple[re.Pattern[str], str], ...] + #: 判断词前面的否定(_negated) + negation: re.Pattern[str] + #: 否定词和判断词之间可以隔着的填充词(「并未出现明显异常」) + filler: re.Pattern[str] + #: 推测的说法:因果句有它就不算没依据 + guess: re.Pattern[str] + #: 因果说的是数据本身(数据只到哪天、口径、样本):不当原因判断核 + method: re.Pattern[str] + #: 「异常」「正常」前面是这些的,说的是数据质量(数据异常、系统无异常),不是指标的波动 + quality: re.Pattern[str] + #: 拖累、拉动、带动:点名的段不在 subjects 里时,按那一段变化的正负和占比核 + pulls: frozenset[str] = field(default_factory=frozenset) + + def claim(self, key: str) -> Claim: + return next(c for c in self.claims if c.key == key) + + +_V1 = Lexicon( + version=1, + claims=( + Claim("source", "来源", "decompose", re.compile( + r"主要(?:来自|源自|出自|由|集中(?:在|于))" + rf"|主要是(?!因为|由于|受|指|看|说|想|希望){_NOT_STOP}{{0,12}}?(?:{_DIR}|贡献|拖累|带动|拉动|驱动)" + r"|(?:绝)?大(?:部分|多数|多)(?:来自|源自|出自|由|集中(?:在|于))" + r"|集中(?:在|于)" + r"|主导(?!地位|产品|品类|品牌|产业)" + r"|拖累|拉动|带动" + r"|贡献(?:最大|最多|最高)|最大(?:的)?贡献|贡献了(?:绝)?大部分"), flip="source_not"), + Claim("source_not", "来源(否定)", "decompose", re.compile(r"(?!)"), negative=True), + Claim("dispersed", "分散", "decompose", re.compile( + r"分散(?!注意|精力|风险|投资|采购)" + rf"|普遍(?:有所|出现|呈现)?{_DIR}" + rf"|全面{_DIR}" + rf"|各(?:个)?{_NOT_STOP}{{1,6}}?(?:都|均)(?:有所|出现|在)?{_DIR}"), flip="source"), + Claim("offset", "抵消", "decompose", re.compile(r"抵消|抵冲|此消彼长|一增一减|一升一降|有增有减")), + Claim("mix", "结构", "decompose", re.compile( + r"结构性|结构(?:变化|变动|效应)|占比(?:的)?变化(?:带来|造成|导致|引起)"), mode="ratio"), + Claim("anomaly", "异常", "baseline", re.compile( + r"异常(?!订单|单|值|数据|记录|交易|码|状态|类|退款|商品|门店|账户|用户|日志|处理|检测)" + r"|反常|罕见" + r"|(?:明显|显著|大幅|严重)偏离|偏离(?:了)?(?:正常|常规|往常|以往|历史|过往)" + rf"|(?:明显|显著)?(?:超出|超过|跳出|突破|高于|低于)(?:了)?{_NOT_STOP}{{0,14}}?(?:正常|常规)(?:的)?(?:波动)?(?:范围|水平|区间)" + r"|超出(?:了)?(?:正常|常规)" + rf"|大幅(?:度)?(?:地)?(?:{_DIR}|波动|变化|变动)" + r"|骤降|骤减|暴跌|暴降|锐减|激增|飙升|暴涨|猛增|骤增|陡增|陡降" + r"|剧烈(?:地)?(?:波动|变化|变动|震荡|起伏)|(?:波动|变化|变动)(?:十分|非常|较为|比较)?剧烈"), + flip="normal"), + Claim("record", "新高新低", "baseline", re.compile( + r"历史(?:新高|新低|最高|最低)|创(?:下)?(?:了)?(?:历史)?(?:新高(?!地)|新低)|前所未有")), + Claim("normal", "正常", "baseline", re.compile( + r"(?:正常|常规)(?:的)?波动(?:范围)?(?:内|之内)?" + r"|(?:正常|常规)(?:的)?(?:范围|区间)(?:内|之内)?" + r"|(?:属于|处于|在)(?:正常|常规)(?:水平|区间|范围)"), flip="anomaly"), + Claim("normal", "正常", "baseline", re.compile( + r"(?:并不|并非|并没有|没有|未见|并无|不算|不属于|不是)(?:明显)?(?:的)?异常|无异常"), negative=True), + Claim("trend", "趋势", "trend", re.compile( + rf"{_DIR}(?:的)?(?:趋势|态势|势头)" + rf"|(?:趋势|态势|势头)(?:性)?(?:地)?{_DIR}" + rf"|(?:呈|呈现|保持|维持|显示)(?:出)?{_DIR}?(?:的)?(?:趋势|态势)" + rf"|持续(?:地|性)?{_DIR}" + rf"|一路(?:{_DIR}|走高|走低|上扬)" + rf"|逐步{_DIR}|稳步{_DIR}" + r"|节节(?:攀升|升高|走高|上涨|上升|下滑|下降|败退|走低)"), flip="no_trend"), + Claim("trend", "趋势", "trend", re.compile( + rf"连续(?:[\x00\s0-90-9一二三四五六七八九十两几多数个周月天日季度年期]|都|在|有所|出现)*?{_DIR}"), + flip="no_trend", run=True), + Claim("no_trend", "无趋势", "trend", re.compile( + r"(?:没有|并没有|没|无|未见|并无|未呈现|未出现)(?:明显|显著)?(?:的)?" + r"(?:(?:上升|下降|增长|下滑|向上|向下)(?:或|和|、|与|/)?)*(?:的)?(?:趋势|态势)" + rf"|{_DIR}?(?:的)?(?:趋势|态势)(?:并)?(?:不明显|不显著|不清晰|不突出)" + r"|基本平稳|走势平稳"), negative=True), + Claim("differ", "差异", "differ", re.compile( + r"(?:显著|明显)(?:地)?(?:高于|低于|大于|小于|多于|少于|好于|差于|优于|劣于)" + r"|确实(?:更高|更低|更多|更少|高于|低于)" + r"|差(?:异|别)(?:十分|非常|很|较为)?(?:明显|显著)" + r"|(?:明显|显著)(?:的)?(?:差异|差别)"), flip="no_diff"), + Claim("no_diff", "无差异", "differ", re.compile( + r"差(?:异|别)(?:不大|很小|较小|不明显|并不明显|不显著|有限)" + r"|(?:没有|并没有|没|无|并无)(?:明显|显著)?(?:的)?(?:差异|差别|区别)" + r"|不相上下|旗鼓相当" + rf"|(?:基本|大致|大体)?相当(?=[{_STOPS}\s\x00]|$)"), negative=True), + Claim("causal", "因果", None, re.compile( + r"因为|由于|导致|造成|引起(?!关注|重视|注意|警惕|讨论|兴趣)|归因(?:于|为)|原因(?:主要)?(?:是|在于)" + r"|源于|所致|得益于" + rf"|受(?!到?影响)(?:到)?{_NOT_STOP}{{1,12}}?(?:的)?影响")), + ), + intrinsic=( + (re.compile(r"拖累|骤降|骤减|暴跌|暴降|锐减|陡降|新低|最低|低于|小于|少于|更低|更少"), "down"), + (re.compile(r"拉动|带动|激增|飙升|暴涨|猛增|骤增|陡增|新高|最高|高于|大于|多于|更高|更多"), "up"), + ), + negation=re.compile(r"不(?![但仅只光论少同断久管过如然错禁免妨要])|没有|没|并非|并不|未(?![来必])|无(?![论疑关需])"), + filler=re.compile(r"(?:出现|发现|看到|见到|存在|呈现|表现出|明显|显著|什么|任何|多大|太|很|特别|有|过|的|了|[\x00\s])$"), + guess=re.compile(r"可能|或许|也许|推测|猜测|待核实|有待核实|需(?:要)?(?:进一步)?(?:核实|确认|验证)|待确认|待验证" + r"|不排除|疑似|大概率"), + method=re.compile(r"数据|口径|统计|查询|目录|样本|取数|截断|截止|只到|不完整|未覆盖|篇幅|省略|证据"), + quality=re.compile(r"(?:数据|系统|接口|取数|口径|同步|查询|日志|字段|格式|编码)(?:出现|存在|有|无|没有|并无|未见)?$"), + pulls=frozenset({"拖累", "拉动", "带动"}), +) + +LEXICONS: dict[int, Lexicon] = {1: _V1} + +#: 能挂「主要来自」这类来源判断的拆解判定(判定语就是这么说的):一段或一个因子为主、集中在前几段,比率拆解里结构为主、 +#: 各段自身为主 +_SOURCE_VERDICTS = frozenset({"driver", "concentrated", "mix_driven", "rate_driven"}) +#: 有这几类判断的分句里,因果词并进它们核(「下降主要由华东造成」:说的是记账意义上的来源) +_SOURCE_KEYS = frozenset({"source", "source_not", "dispersed", "offset", "mix"}) +#: 拆解结果表里不是维度的列(params.by 对不上时按「不是度量列」认维度,跳过这些) +_MEASURE_COLUMNS = frozenset({ + "base", "target", "delta", "pct", "share", "flag", "n_base", "n_target", "d_base", "d_target", "w_base", + "w_target", "r_base", "r_target", "mix", "rate", "total", "contrib", +}) +#: 一段的变化记在哪一列:可加拆解的 delta、比率拆解的 total(结构 + 自身)、乘积拆解的 contrib +_DELTA_COLUMNS = ("delta", "total", "contrib") + + +def lexicon(version: int | None = None) -> Lexicon: + """某一版说法表;不认识的版本按当前版。""" + return LEXICONS.get(version if isinstance(version, int) else LEXICON_VERSION, LEXICONS[LEXICON_VERSION]) + + +# -------------------------------------------------------------------------- +# 扫判断词 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class Hit: + """句子里的一处判断词:类(否定翻过之后的)、在句子里的起止、原文、方向(up / down / None)。""" + + claim: str + start: int + end: int + word: str + direction: str | None + negated: bool = False + run: bool = False + + +def _clause(text: str, start: int, end: int) -> tuple[int, int]: + """[start, end) 所在的分句:往前往后各找到最近的句读。""" + left = max((text.rfind(ch, 0, start) for ch in _STOPS), default=-1) + 1 + rights = [i for i in (text.find(ch, end) for ch in _STOPS) if i >= 0] + return left, min(rights) if rights else len(text) + + +def _negated(lex: Lexicon, before: str) -> bool: + """判断词前 4 个字以内有否定(先去掉紧挨着的填充词:「并未出现明显异常」的否定隔着「出现明显」)。""" + while (m := lex.filler.search(before)) and m.group(0): + before = before[:m.start()] + return lex.negation.search(before[-4:]) is not None + + +def _direction(lex: Lexicon, word: str, after: str, clause: str) -> str | None: + """判断词说的方向:判断词本身带的(骤降、拉动),再看判断词里、紧跟着的几个字、整个分句里的涨跌说法。一个分句里 + 涨跌都有的不判方向。""" + for pattern, direction in lex.intrinsic: + if pattern.search(word): + return direction + for text in (word, after[:4], clause): + up, down = bool(_UP_RE.search(text)), bool(_DOWN_RE.search(text)) + if up != down: + return "up" if up else "down" + if up and down: + return None + return None + + +def scan(text: str, *, version: int | None = None) -> list[Hit]: + """一句话里的判断词(text 是写作者自己写的字,别的片段已经涂成 \\x00)。同一处有几种读法时取最靠前、最长的: + 「超出正常范围」是异常不是正常,「没有明显的上升或下降趋势」是无趋势不是趋势。""" + lex = lexicon(version) + found: list[tuple[int, int, int, Claim]] = [] + for order, claim in enumerate(lex.claims): + for m in claim.words.finditer(text): + if m.end() > m.start(): + found.append((m.start(), -(m.end() - m.start()), order, claim)) + hits: list[Hit] = [] + taken = 0 + for start, minus, _, claim in sorted(found, key=lambda f: (f[0], f[1], f[2])): + end = start - minus + if start < taken: + continue + left, right = _clause(text, start, end) + before = text[left:start] + if claim.key in ("anomaly", "normal") and lex.quality.search( + re.sub(r"(?:不|没有|没|并不|并非|未|无)$", "", before.rstrip("\x00 "))): + taken = end + continue + key, negated = claim.key, False + if not claim.negative and _negated(lex, before): + negated = True + if claim.flip is None: + taken = end + continue + key = claim.flip + word = text[start:end] + direction = _direction(lex, word, text[end:right], text[left:right]) + hits.append(Hit(claim=key, start=start, end=end, word=word, direction=direction, negated=negated, + run=claim.run and not negated)) + taken = end + return hits + + +# -------------------------------------------------------------------------- +# 一句话 +# -------------------------------------------------------------------------- + + +@dataclass +class Sentence: + """交给核对的一句话(和标记解析解耦:文档里怎么切、怎么解析引用由 evidence 管,这里只要组装好的单元)。 + + text、names、shown 等长,位置一一对应:text 只留写作者自己写的字(判断词在这里找),names 另留引用渲染出来的值(点名 + 的段在这里认),两者都把判定语、知识库原话涂成 \\x00;shown 是给人看的整句(排版符号涂成 \\x00,显示时去掉)。没给 + names、shown 的按 text。analyses 是这句的分析依据(A 编号),quoted / inputs:同一句里有知识库原话、运行输入。base 是 + text[0] 在正文里的位置(违规带 span 要用),pieces 是各片段在 text 里的起止和编号(违规带所在片段)。""" + + text: str + names: str = "" + shown: str = "" + analyses: list[str] = field(default_factory=list) + quoted: bool = False + inputs: bool = False + base: int | None = None + unit: str | None = None + pieces: list[tuple[int, int, str | None]] = field(default_factory=list) + + def __post_init__(self) -> None: + if len(self.names) != len(self.text): + self.names = self.text + if len(self.shown) != len(self.text): + self.shown = self.names + + +def _same_length_norm(text: str) -> str: + """逐字归一(NFKC 会把个别字展开成几个字,逐字做、展开的取第一个,位置就和原文对得上)。""" + out = [] + for ch in text: + n = unicodedata.normalize("NFKC", ch).casefold() + out.append(n[:1] if n else ch) + return "".join(out) + + +_NUMERIC = re.compile(r"^[\d.,+\-%‰\s]+$") + + +def _named_value(value: Any) -> str | None: + """结果表里一个维度值能不能拿来认点名:两个字以上、不是纯数字。""" + if value is None or isinstance(value, bool): + return None + text = _same_length_norm(str(value).strip()) + if len(text) < 2 or _NUMERIC.match(text): + return None + return text + + +def _dims(result: Mapping[str, Any]) -> list[int]: + """结果表里各段名字所在的列:拆解按 params.by(照输入的列名),乘积拆解是 factor 列(因子的叫法),差异检验是 a、b 两组; + 拆解的 by 对不上表头时按「不是度量列」认。别的算子没有段。""" + table = result.get("table") or {} + columns = [str(c) for c in table.get("columns") or []] + if result.get("op") == "differ": + return [columns.index(c) for c in ("a", "b") if c in columns] + if result.get("op") != "decompose": + return [] + if result.get("mode") == "factor" and "factor" in columns: + return [columns.index("factor")] + by = (result.get("params") or {}).get("by") + wanted = by if isinstance(by, list) else [by] if isinstance(by, str) else [] + picked = [columns.index(str(b)) for b in wanted if str(b) in columns] + return picked or [i for i, c in enumerate(columns) if c not in _MEASURE_COLUMNS] + + +def _segment_names(result: Mapping[str, Any]) -> dict[str, str]: + """{归一后的维度值或因子名: 原样}:结果表里各段的维度值,加上判定点名的 subjects。""" + out: dict[str, str] = {} + rows = (result.get("table") or {}).get("rows") or [] + for row in rows if isinstance(rows, list) else []: + if not isinstance(row, list): + continue + for i in _dims(result): + if i < len(row) and (named := _named_value(row[i])): + out.setdefault(named, str(row[i]).strip()) + for subject in _subjects(result): + if named := _named_value(subject): + out.setdefault(named, subject) + return out + + +def _verdict(result: Mapping[str, Any]) -> Mapping[str, Any]: + verdict = result.get("verdict") + return verdict if isinstance(verdict, Mapping) else {} + + +def _subjects(result: Mapping[str, Any]) -> list[str]: + verdict = _verdict(result) + out: list[str] = [] + for subject in verdict.get("subjects") or []: + values = subject if isinstance(subject, list) else [subject] + out.extend(str(v).strip() for v in values if v is not None) + return out + + +def _named(result: Mapping[str, Any], names: str) -> list[str]: + """分句里点名的段(原样,按出现的先后)。ASCII 的名字要整词出现(「A」不算点名了「AB」)。""" + flat = _same_length_norm(names) + hits: list[tuple[int, str]] = [] + for key, original in _segment_names(result).items(): + at = flat.find(key) + while at >= 0: + before, after = flat[at - 1:at], flat[at + len(key):at + len(key) + 1] + if not (key.isascii() and any(ch.isascii() and ch.isalnum() for ch in (before, after) if ch)): + hits.append((at, original)) + break + at = flat.find(key, at + 1) + return [name for _, name in sorted(hits)] + + +def _decimal(value: Any) -> Decimal | None: + if value is None or isinstance(value, bool): + return None + try: + return Decimal(str(value).replace(",", "")) + except (InvalidOperation, ValueError): + return None + + +def _segment_change(result: Mapping[str, Any], name: str) -> tuple[Decimal | None, Decimal | None]: + """一段(维度值或因子名)的变化和占总变化的比重:结果表里这一段所在各行的变化相加;表里没有的为 None。""" + table = result.get("table") or {} + columns = [str(c) for c in table.get("columns") or []] + col = next((columns.index(c) for c in _DELTA_COLUMNS if c in columns), None) + if col is None: + return None, None + share_col = columns.index("share") if "share" in columns else None + want = _named_value(name) + total: Decimal | None = None + share: Decimal | None = None + for row in table.get("rows") or []: + if not isinstance(row, list) or not any(i < len(row) and _named_value(row[i]) == want for i in _dims(result)): + continue + if (d := _decimal(row[col] if col < len(row) else None)) is not None: + total = d if total is None else total + d + if share_col is not None and (s := _decimal(row[share_col] if share_col < len(row) else None)) is not None: + share = s if share is None else share + s + return total, share + + +def _both_ways(result: Mapping[str, Any]) -> bool: + """结果表里各段的变化有涨有跌。""" + table = result.get("table") or {} + columns = [str(c) for c in table.get("columns") or []] + col = next((columns.index(c) for c in _DELTA_COLUMNS if c in columns), None) + if col is None: + return False + signs = {d > 0 for row in table.get("rows") or [] if isinstance(row, list) and col < len(row) + and (d := _decimal(row[col])) is not None and d != 0} + return signs == {True, False} + + +def _caveats(result: Mapping[str, Any]) -> set[str]: + return {str(c.get("code")) for c in result.get("caveats") or [] if isinstance(c, dict)} + + +def _value(result: Mapping[str, Any], key: str) -> Decimal | None: + return _decimal((result.get("values") or {}).get(key)) + + +def _dir_word(direction: str | None) -> str: + return {"up": "上升", "down": "下降"}.get(direction or "", "") + + +def _run_direction(raw: Any) -> str | None: + text = str(raw or "").strip().lower() + if text in ("up", "rising", "上升"): + return "up" + if text in ("down", "falling", "下降"): + return "down" + return None + + +# -------------------------------------------------------------------------- +# 判定对不对得上 +# -------------------------------------------------------------------------- + + +@dataclass(frozen=True) +class _Miss: + """一份结论对不上的原因:给写作者的、给人看的各一句(不带结论编号,外面接上)。""" + + model: str + human: str + + +def _phrase(result: Mapping[str, Any]) -> str: + return str(result.get("phrase") or "").strip() + + +def _verdict_miss(result: Mapping[str, Any]) -> _Miss: + said = f"判定是「{_phrase(result)}」" if _phrase(result) else "判定不是这一类" + return _Miss(said, said) + + +def _check(lex: Lexicon, hit: Hit, result: Mapping[str, Any], names: str) -> _Miss | None: + """这处判断词能不能挂这份结论:对得上返回 None,对不上返回原因。names 是判断词所在分句(点名用的样子)。""" + if result.get("status") != "ok": + reason = str(result.get("reason") or "算不了") + return _Miss(f"没有做成({reason})", f"这份结论没有做成({reason})") + verdict = _verdict(result) + code = verdict.get("code") + key = hit.claim + if key in ("source", "source_not"): + subjects = _subjects(result) + named = _named(result, names) + # 判定语说「主要来自」的几种:一段(一个因子)为主、集中在前几段;比率拆解的结构为主、各段自身为主 + top = code in _SOURCE_VERDICTS + if key == "source_not": + inside = [n for n in named if _named_value(n) in {_named_value(s) for s in subjects}] + if top and (inside or not named): + who = "、".join(inside or subjects) + return _Miss(f"判的主要来源正是{who}" if who else _verdict_miss(result).model, + f"判定的主要来源正是{who}" if who else _verdict_miss(result).human) + return None + if not top: + return _verdict_miss(result) + wanted = {_named_value(s) for s in subjects} + stray = [n for n in named if _named_value(n) not in wanted] + pull = hit.word in lex.pulls + if stray and pull: + # 拖累、拉动、带动:点名的段不在主要来源里,变化方向对、占总变化过半的也算(整体上涨、华东下跌拖累了涨幅) + main = _decimal((result.get("settings") or {}).get("main_share")) or Decimal("0.5") + stray = [n for n in stray if not ((share := _segment_change(result, n)[1]) is not None + and abs(share) >= main)] + if stray: + subject = "、".join(subjects) + return _Miss(f"判的主要来源是{subject},不是{'、'.join(stray)}", + f"判定的主要来源是{subject},不是{'、'.join(stray)}") + if pull and hit.direction: + for name in named or subjects: + change, _ = _segment_change(result, name) + if change is None or change == 0: + continue + if (change > 0) != (hit.direction == "up"): + moved = "上升" if change > 0 else "下降" + return _Miss(f"里{name}的变化是{moved},不能说「{hit.word}」", + f"其中{name}的变化是{moved},与「{hit.word}」的方向相反") + return None + if key == "dispersed": + return None if code == "dispersed" else _verdict_miss(result) + if key == "offset": + # 抵消记在 offset 里;判定为基本持平的,判定语本身就说了此消彼长(不一定再接 offset),各段有涨有跌就算 + if "offset" in _caveats(result) or (code == "flat" and _both_ways(result)): + return None + return _Miss("没有记下此消彼长(各段的变化方向大多一致)", "这份结论没有记下各段此消彼长") + if key == "mix": + if result.get("mode") != "ratio": + done, wanted = method_label("decompose", result.get("mode")), method_label("decompose", "ratio") + return _Miss(f"是{done},说明不了结构变化:结构变化要挂{wanted}", + f"这是{done},说明不了结构变化:结构变化要挂{wanted}") + return None if code in ("mix_driven", "both") else _verdict_miss(result) + if key == "anomaly": + if code not in ("outside_band", "far_outside_band"): + return _verdict_miss(result) + return _direction_miss(hit, verdict.get("direction")) + if key == "record": + caveats = _caveats(result) + wanted = {"up": {"record_high"}, "down": {"record_low"}}.get(hit.direction or "", {"record_high", "record_low"}) + if caveats & wanted: + return None + return _Miss("没有记下本期是历史最高或最低", "这份结论没有记下本期是历史最高或最低") + if key == "normal": + return None if code == "within_band" else _verdict_miss(result) + if key == "trend": + if code not in ("rising", "falling"): + return _verdict_miss(result) + if miss := _direction_miss(hit, "up" if code == "rising" else "down"): + return miss + if hit.run: + run = _value(result, "run_length") + if run is None or run < 3: + shown = "没有" if run is None else f"只有 {run} 期" + return _Miss(f"末尾连续同向的期数{shown},不够说「连续」(至少 3 期)", + f"末尾连续同向的期数{shown},不够说「连续」") + ran = _run_direction((result.get("values") or {}).get("run_direction")) + if ran and hit.direction and ran != hit.direction: + return _Miss(f"末尾连续{_dir_word(ran)},不是连续{_dir_word(hit.direction)}", + f"末尾连续{_dir_word(ran)},与「{hit.word}」的方向相反") + return None + if key == "no_trend": + return None if code == "no_trend" else _verdict_miss(result) + if key == "differ": + if code != "differs": + return _verdict_miss(result) + subjects = _subjects(result) + direction = verdict.get("direction") + if len(subjects) == 2 and hit.direction and direction in ("up", "down"): + # 判定语的写法是「A 的…高于 B」:A 是 subjects 的第一个。句子里两组都点名了才核方向,后点名的先写就反过来 + flat = _same_length_norm(names) + spots = [flat.find(_named_value(s) or "￿") for s in subjects] + if all(at >= 0 for at in spots): + expected = direction if spots[0] < spots[1] else ("down" if direction == "up" else "up") + if expected != hit.direction: + higher, lower = (subjects if direction == "up" else subjects[::-1]) + return _Miss(f"判的是{higher}高于{lower},方向写反了", f"判定是{higher}高于{lower},方向写反了") + return None + if key == "no_diff": + return None if code == "no_evidence" else _verdict_miss(result) + return None + + +def _direction_miss(hit: Hit, direction: Any) -> _Miss | None: + if hit.direction and direction in ("up", "down") and hit.direction != direction: + return _Miss(f"判的方向是{_dir_word(direction)},不是{_dir_word(hit.direction)}", + f"判定的方向是{_dir_word(direction)},与「{hit.word}」相反") + return None + + +# -------------------------------------------------------------------------- +# 违规 +# -------------------------------------------------------------------------- + +#: 没挂对分析结论时交回写作者的「那就怎么写」 +_FALLBACK = { + "decompose": "只写各段各自的变化,不下「主要」「集中」「拖累」「分散」这类判断", + "mix": "只写比率和各段的变化,不说结构变化", + "baseline": "只写本期的数和变化,不说「异常」「大幅」「激增」「历史新高」「正常波动」这类判断", + "trend": "只写各期的数,不说「持续」「趋势」「连续」这类判断", + "differ": "只写各组各自的数,不说「显著」「明显高于」「差异不大」这类判断", +} + + +def _op_text(claim: Claim) -> str: + """这一类要挂的分析怎么叫:算子、模式的叫法从契约取(结构变化是「变化拆解(比率)」)。""" + return method_label(claim.op, claim.mode) if claim.mode else OP_LABELS.get(claim.op or "", claim.op or "") + + +def _snippet(shown: str, start: int, end: int, limit: int = 16) -> str: + """判断词连同它后面半句(给人看的样子),最多 limit 个字。""" + right = _clause(shown, start, end)[1] + piece = shown[start:max(end, min(right, start + limit))].replace("\x00", "").strip() + return piece or shown[start:end] + + +def _uncited(claim: Claim, word: str, available: Mapping[str, list[str]]) -> _Reason: + op_text = _op_text(claim) + pool = available.get(f"{claim.op}:{claim.mode}" if claim.mode else claim.op or "", []) + fallback = _FALLBACK["mix" if claim.mode == "ratio" else claim.op or "decompose"] + if pool: + model = (f"「{word}」要挂{op_text}的结论:照它的判定写、句末挂 [[see:{pool[0]}]],或者直接引用判定 [[a:{pool[0]}]];" + f"判定和你想写的不一样就照判定写,否则{fallback}") + else: + model = f"这次没有{op_text}的结论,不能写「{word}」:{fallback}" + return _Reason(f"「{word}」是分析判断,这句没有挂{op_text}的分析结论,系统无法核对", model) + + +def _mismatch(alias: str, snippet: str, miss: _Miss) -> _Reason: + return _Reason(f"「{snippet}」与所挂的分析结论 {alias} 对不上:{miss.human}", + f"{alias} {miss.model},不能写「{snippet}」:照判定改写(或者直接引用判定 [[a:{alias}]])," + "或者删掉这个判断") + + +def _causal(snippet: str) -> _Reason: + return _Reason(f"「{snippet}」是原因判断,这句没有知识库原话或运行输入作依据,也没有写成推测", + f"「{snippet}」没有依据:数据只能说明变化来自哪里;要写原因,引用知识库原话,或写成「可能与…有关,待核实」") + + +def check_sentence(sentence: Sentence, results: Mapping[str, Mapping[str, Any]], *, + available: Mapping[str, list[str]] | None = None, version: int | None = None) -> list[dict[str, Any]]: + """一句话的说法违规。results 是写作目录里的分析结论 {A 编号: 结论},available 是 {op: [这次有的 A 编号]}(没挂时 + 告诉写作者可以挂哪一份),不给就按 results 算。""" + lex = lexicon(version) + if available is None: + available = _available(results) + hits = scan(sentence.text, version=lex.version) + if not hits: + return [] + mine = [(a, results[a]) for a in dict.fromkeys(sentence.analyses) if a in results] + out: list[dict[str, Any]] = [] + #: 同一分句里同一类只报一处(「由于促销结束导致下降」是一处没依据的原因,不是两处) + seen: set[tuple[str, str, int]] = set() + guessed = lex.guess.search(sentence.text) is not None + for hit in hits: + claim = lex.claim(hit.claim) + left, right = _clause(sentence.text, hit.start, hit.end) + names = sentence.names[left:right] + snippet = _snippet(sentence.shown, hit.start, hit.end) + if claim.key == "causal": + clause = sentence.text[left:right] + if sentence.quoted or sentence.inputs or guessed or lex.method.search(clause): + continue + if any(h is not hit and h.claim in _SOURCE_KEYS and left <= h.start < right for h in hits): + continue # 「主要由华东造成」:并进来源那一处核 + decomposes = [(a, r) for a, r in mine if r.get("op") == "decompose"] + if any(_named(r, names) for _, r in decomposes): + # 因果词点名的是拆解的段或因子:按来源核(记账意义上的「来自」) + hit = Hit("source", hit.start, hit.end, hit.word, hit.direction) + claim = lex.claim("source") + else: + key = (CAUSAL, claim.key, left) + if key not in seen: + seen.add(key) + out.append(_record(CAUSAL, _causal(snippet), sentence, hit, claim, mine)) + continue + candidates = [(a, r) for a, r in mine if r.get("op") == claim.op] + if not candidates: + key = (UNCITED, claim.key, left) + if key not in seen: + seen.add(key) + out.append(_record(UNCITED, _uncited(claim, hit.word, available), sentence, hit, claim, mine)) + continue + misses = [(a, _check(lex, hit, r, names)) for a, r in candidates] + if any(miss is None for _, miss in misses): + continue + alias, miss = misses[0] + key = (MISMATCH, claim.key, left) + if key not in seen: + seen.add(key) + out.append(_record(MISMATCH, _mismatch(alias, snippet, miss), sentence, hit, claim, mine)) # type: ignore[arg-type] + return out + + +def _record(code: str, message: _Reason, sentence: Sentence, hit: Hit, claim: Claim, + mine: list[tuple[str, Mapping[str, Any]]]) -> dict[str, Any]: + span = [sentence.base + hit.start, sentence.base + hit.end] if sentence.base is not None else None + segment = next((sid for s, e, sid in sentence.pieces if s <= hit.start < e), None) + shown = sentence.shown.replace("\x00", "").strip() + return _violation(code, message, text=hit.word, span=span, context=shown[:200] or None, + unit=sentence.unit, segment=segment, claim=claim.key, op=claim.op, + **({"mode": claim.mode} if claim.mode else {}), analyses=[a for a, _ in mine]) + + +def _available(results: Mapping[str, Mapping[str, Any]]) -> dict[str, list[str]]: + """{op: [这次有的 A 编号]},另按「op:mode」再记一份(结构变化要比率拆解)。只收做成了的:没挂时不教写作者去挂一份 + 算不了的结论。""" + out: dict[str, list[str]] = {} + for alias, result in results.items(): + if result.get("status") != "ok": + continue + op = str(result.get("op") or "") + out.setdefault(op, []).append(alias) + if result.get("mode"): + out.setdefault(f"{op}:{result['mode']}", []).append(alias) + return out + + +# -------------------------------------------------------------------------- +# 报告文档 +# -------------------------------------------------------------------------- + + +def results_of(catalog: Mapping[str, Any], load: Any = None) -> dict[str, dict[str, Any]]: + """写作目录里的分析结论:{A 编号: 结论}(contract.catalog_result 读)。条目只带摘要、不带整份结论的(存进报告文档的 + 目录就是这样)按 load(编号, 条目) 取回(evidence 的 _Snapshots.analysis:按工件取、复验哈希);没给 load、取不回的 + 不在里面。""" + out: dict[str, dict[str, Any]] = {} + for alias, entry in catalog.items(): + if not isinstance(entry, dict) or entry.get("kind") != LEDGER_KIND: + continue + result = catalog_result(entry) + if result is None and load is not None: + result = load(str(alias), entry) + if isinstance(result, dict): + out[str(alias)] = dict(result) + return out + + +def _sentence(unit: dict[str, Any], aliases: Iterable[str], results: Mapping[str, Any]) -> Sentence | None: + """文档里的一个句子单元 → Sentence。写作者自己写的字(文字片段、没有出处的数字)留在 text;引用渲染出来的值、表名 + 字段名留在 names(点名用);判定语(a:)、知识库原话(q:)、排版符号两边都涂掉。""" + segments = [s for s in unit.get("segments") or [] if isinstance(s, dict)] + if not segments: + return None + scan_parts: list[str] = [] + name_parts: list[str] = [] + shown_parts: list[str] = [] + pieces: list[tuple[int, int, str | None]] = [] + quoted = False + pos = 0 + for seg in segments: + text = str(seg.get("text") or "") + kind, ref = seg.get("kind"), str(seg.get("ref") or "") + head = ref.partition(":")[0].strip() if ref else "" + blank = "\x00" * len(text) + if kind == "structural": + scan_parts.append(blank) + name_parts.append(blank) + elif head in ("a", "q"): + scan_parts.append(blank) + name_parts.append(blank) + quoted = quoted or (head == "q" and seg.get("state") == "deterministic") + elif ref or kind == "entity": + scan_parts.append(blank) + name_parts.append(text) + else: + scan_parts.append(text) + name_parts.append(text) + shown_parts.append(blank if kind == "structural" else text) + pieces.append((pos, pos + len(text), seg.get("id"))) + pos += len(text) + span = segments[0].get("span") + base = span[0] if isinstance(span, list) and span and isinstance(span[0], int) else None + cited = list(dict.fromkeys(str(a) for a in aliases)) + return Sentence(text="".join(scan_parts), names="".join(name_parts), shown="".join(shown_parts), + analyses=[a for a in cited if a in results], quoted=quoted, + inputs=any(a.startswith("i:") for a in cited), base=base, unit=unit.get("id"), pieces=pieces) + + +def check_doc(doc: dict[str, Any], catalog: Mapping[str, Any], *, cited: Mapping[int, list[str]] | None = None, + version: int | None = None, load: Any = None) -> list[dict[str, Any]]: + """一份报告文档的说法违规。cited 是 {id(unit): 这句按重新解析的引用算的依据}(verify_doc 交进来),不给就用文档里 + 记的 cites;load 取回只带摘要的条目的整份结论(results_of)。标题、代码块、表头不核。""" + results = results_of(catalog, load) + available = _available(results) + out: list[dict[str, Any]] = [] + for block, unit in iter_units(doc): + if block.get("type") in ("heading", "code") or unit.get("kind") in ("heading", "code") \ + or (unit.get("loc") or {}).get("row") == -1: + continue + aliases = cited.get(id(unit), []) if cited is not None else unit.get("cites") or [] + sentence = _sentence(unit, aliases, results) + if sentence is not None: + out.extend(check_sentence(sentence, results, available=available, version=version)) + return out + + +def record(mode: str) -> dict[str, Any]: + """报告文档里记下的那一项:按哪种处置、哪一版说法表核。""" + return {"mode": mode, "lexicon": LEXICON_VERSION} + + +def recorded(doc: Any) -> tuple[str | None, int | None] | None: + """文档记下的 (处置, 说法表版本):没有这一项(老文档、报告节点关掉了核对)返回 None;记了认不出的值,认不出的那一样 + 为 None。""" + if not isinstance(doc, dict) or DOC_FIELD not in doc: + return None + raw = doc.get(DOC_FIELD) + raw = raw if isinstance(raw, dict) else {} + mode = raw.get("mode") if raw.get("mode") in MODES else None + version = raw.get("lexicon") if type(raw.get("lexicon")) is int and raw.get("lexicon") in LEXICONS else None + return mode, version + + +def verify(doc: Any, catalog: Mapping[str, Any], *, cited: Mapping[int, list[str]] | None = None, + load: Any = None) -> list[dict[str, Any]] | None: + """复核一份文档的说法(evidence.verify_doc 调):没记这一项的文档返回 None(不核,老文档复核结果不变);记了的按记下 + 的那一版说法表核。记了认不出的处置、版本的另记一条 bad_schema(文档可能被改过),照当前版核。""" + found = recorded(doc) + if found is None: + return None + mode, version = found + out: list[dict[str, Any]] = [] + if mode is None or version is None: + out.append(_violation("bad_schema", f"报告文档记录的分析说法核对规则「{doc.get(DOC_FIELD)}」无法识别")) + return out + check_doc(doc, catalog, cited=cited, version=version, load=load) + + +def counts(violations: Iterable[Mapping[str, Any]]) -> dict[str, int]: + """三种说法违规各几处(只数有的)。""" + out: dict[str, int] = {} + for v in violations: + if v.get("code") in CODES: + out[str(v["code"])] = out.get(str(v["code"]), 0) + 1 + return out + + +def summary(violations: list[Mapping[str, Any]]) -> str: + """几处说法违规怎么说:「1 处判断没挂分析结论、2 处与所挂结论的判定对不上、1 处原因没有依据」。""" + said = {UNCITED: "判断没挂分析结论", MISMATCH: "与所挂结论的判定对不上", CAUSAL: "原因没有依据"} + found = counts(violations) + return "、".join(f"{found[code]} 处{said[code]}" for code in (UNCITED, MISMATCH, CAUSAL) if code in found) + + +# -------------------------------------------------------------------------- +# 写作规则(给模型看) +# -------------------------------------------------------------------------- + +#: 写作目录里有分析结论时,拼在写作规则后面 +ANALYSIS_RULES_PROMPT = ( + "分析结论(系统会逐句核对判断词):\n" + "- 「主要来自」「集中在」「拖累」「带动」「分散」「异常」「大幅」「激增」「历史新高」「正常波动」「持续上升」「趋势」" + "「显著高于」「差异不大」这类判断,只能照证据目录里分析结论的判定写,句末挂对应的依据,比如 [[see:A1]];最好直接引用" + "判定语 [[a:A1]],它由系统按判定渲染。来源、集中、拖累、分散挂变化拆解,结构变化挂比率拆解,异常、新高新低、正常波动" + "挂波动基线,持续、趋势、连续挂趋势,显著、明显高于、差异不大挂差异检验。\n" + "- 判定和你想写的不一样时照判定写;点名的地区、渠道要在判定点名的段里;没有做成的分析照实写没做成的原因,不下这类判断。" + "没有对应的分析结论,就只陈述数字和变化。\n" + "- 拆解只说明变化来自哪里,不说明为什么。写原因(因为、由于、导致、受…影响)要有知识库原话或运行输入作依据," + "否则写成待核实的推测,比如「可能与促销结束有关,待核实」。" +) +#: 写作目录里没有分析结论时,拼在写作规则后面 +ANALYSIS_NONE_PROMPT = ( + "判断词(系统会逐句核对):这次没有分析结论,不要写「主要来自」「集中在」「拖累」「带动」「分散」「异常」「大幅」" + "「激增」「历史新高」「正常波动」「持续上升」「趋势」「显著高于」「差异不大」这类判断,只陈述数字和变化(各段各自是多少、" + "变了多少)。写原因(因为、由于、导致、受…影响)要有知识库原话或运行输入作依据,否则写成待核实的推测," + "比如「可能与促销结束有关,待核实」。" +) +#: 重写请求里有说法违规时补的一句 +ANALYSIS_REPAIR_PROMPT = ("判断词照分析结论的判定写并挂上依据,没有对应结论的就删掉判断、只陈述数字和变化;" + "原因没有依据的写成待核实的推测。") + + +def rules_prompt(catalog: Mapping[str, Any]) -> str: + """写作规则里说判断词的那一段:目录里有分析结论和没有时各一种说法。""" + return ANALYSIS_RULES_PROMPT if results_of(catalog) else ANALYSIS_NONE_PROMPT + + +__all__ = [ + "ANALYSIS_NONE_PROMPT", "ANALYSIS_REPAIR_PROMPT", "ANALYSIS_RULES_PROMPT", "CAUSAL", "CODES", "DOC_FIELD", + "LEXICONS", "LEXICON_VERSION", "MISMATCH", "MODES", "UNCITED", "Claim", "Hit", "Lexicon", "Sentence", + "check_doc", "check_sentence", "counts", "lexicon", "record", "recorded", "results_of", "rules_prompt", "scan", + "summary", "verify", +] diff --git a/backend/app/engine/analysis_scope.py b/backend/app/engine/analysis_scope.py new file mode 100644 index 00000000..c5755f54 --- /dev/null +++ b/backend/app/engine/analysis_scope.py @@ -0,0 +1,352 @@ +"""报告文档里系统写的「分析范围」(docs/design/analysis-round/00-总方案.md §3.6,契约 contract.ScopeBlock)。 + +报告里用到了分析结论(这次运行有分析结论)时,系统按写作目录里的 A 条目照实写一段:查了什么、排除了什么、哪些没查。 +它是报告文档的结构化字段 analysis_scope(D17),不进正文、不过裸数字和说法核对(不是模型写的),写作者改不了,随文档 +封存;网页、导出、可验证报告各自按它渲染,编号点得开。 + +- **现象**(phenomena):做成了的可比性、基线、趋势结论 +- **拆过**(decomposed):做成了的变化拆解,按下钻链的先后(上一层在前,下钻的紧跟在它后面) +- **排除**(excluded):判定为分散的拆解、差异可能只是样本波动的检验——拆了没发现集中也是结论 +- **算不了**(refused):各种算子算不了的结论,带原因 +- **没拆**(not_decomposed):候选维度里没拆过的。候选维度确定地从数据目录算:拆解所用查询的 SQL 里的事实表(目录标了 + fact / log;没标的、查询只读一张表时就是它)上标成属性、状态(attribute / status)、不遮罩、取值不多(码值表不超过 + CANDIDATE_MAX 个取值,或者已列全)的列,加上它关联的维度表(目录标了 dimension,或者关系是多对一)上同样的列。 + 拆解按的列对不上目录、读不到目录、认不出事实表的,not_decomposed 为 None,note 写一句为什么核对不了——不乱列 +- **检验**(tests):这次做了几次差异检验(做成了的);corrected:一次检验比了多对的按次数校正过,几次检验之间没有校正, + 做了不止一次时为 False(契约之外加的一项,见交付说明) + +agent 写的 hypothesis 不进这一段(模型写的字不进系统渲染的正文,细案 01 §7.3)。build 是纯函数(目录、遮罩由调用方读好 +交进来);scope_of 给报告节点用,读这次运行的数据目录视图(data/catalog_view),读不到当核对不了,不挡生成。 +""" +from __future__ import annotations + +import logging +from collections.abc import Callable, Iterable, Mapping +from typing import Any + +from app.analysis.contract import ScopeBlock, ScopeItem, catalog_result +from app.data.names import name_key + +logger = logging.getLogger(__name__) + +#: 候选维度「取值不多」的上限:码值表里的取值不超过这么多(取值观察最多也只取这么多,data/catalog_profile_observe) +CANDIDATE_MAX = 50 +#: 现象:可比性、基线、趋势 +_PHENOMENA = ("comparable", "baseline", "trend") +#: 事实表的表类型(数据目录的 kind):流水、日志也是一行一件事 +_FACT_KINDS = ("fact", "log") +#: 候选维度的度量类型 +_DIMENSION_MEASURES = ("attribute", "status") +#: 拆解的输入快照(下钻的上一层不是快照) +_DATA_ROLES = ("data", "base", "target") + +NOTE_NO_CATALOG = "这次运行读不到数据目录,候选维度核对不了" +NOTE_NO_NOTES = "拆解所用的数据源还没有数据目录,候选维度核对不了" +NOTE_NO_DECOMPOSE = "这次没有按维度拆解,候选维度没有核对" +NOTE_NO_QUERY = "拆解所用的查询取不回来,候选维度核对不了" +NOTE_NO_FACT = "拆解所用查询的表在数据目录里认不出哪张是事实表,候选维度核对不了" + + +def _alias_order(alias: str) -> tuple[int, str]: + tail = alias[1:] + return (int(tail), alias) if tail.isdigit() else (1 << 30, alias) + + +def _value(item: Any) -> Any: + """目录里一个项的值:驳回的(rejected)当没有。""" + if not isinstance(item, Mapping) or item.get("status") == "rejected": + return None + return item.get("value") + + +def _dims(result: Mapping[str, Any]) -> list[str]: + """拆解按的维度列(params.by),乘积拆解没有维度。""" + if result.get("op") != "decompose" or result.get("mode") == "factor": + return [] + by = (result.get("params") or {}).get("by") + return [str(b) for b in (by if isinstance(by, list) else [by] if isinstance(by, str) and by else [])] + + +def _dim_labels(result: Mapping[str, Any]) -> list[str]: + labels = ((result.get("table") or {}).get("labels") or {}) + return [str(labels.get(d) or d) for d in _dims(result)] + + +def _code(result: Mapping[str, Any]) -> str | None: + """结论的判定码;没有判定(算不了)为 None。""" + verdict = result.get("verdict") + return verdict.get("code") if isinstance(verdict, Mapping) else None + + +def _item(alias: str, result: Mapping[str, Any], parent: str | None) -> ScopeItem: + return {"alias": alias, "op": str(result.get("op") or ""), "mode": result.get("mode"), + "dims": _dim_labels(result), "verdict": _code(result), + "phrase": str(result.get("phrase") or ""), "parent": parent, + "reason": result.get("reason") if result.get("status") != "ok" else None} + + +def _parent(result: Mapping[str, Any], by_artifact: Mapping[str, str]) -> str | None: + """下钻的上一层:输入里 role 为 parent 的那份结论(按工件对回写作目录里的编号)。""" + for item in result.get("inputs") or []: + if isinstance(item, Mapping) and item.get("role") == "parent" and item.get("artifact") in by_artifact: + return by_artifact[str(item["artifact"])] + return None + + +def _chain(items: list[ScopeItem]) -> list[ScopeItem]: + """按下钻链排:上一层在前,下钻的紧跟在它后面(同一层按编号)。上一层不在这几项里的当作最上层。""" + known = {i["alias"] for i in items} + children: dict[str | None, list[ScopeItem]] = {} + for item in items: + children.setdefault(item["parent"] if item["parent"] in known else None, []).append(item) + out: list[ScopeItem] = [] + seen: set[str] = set() + + def walk(parent: str | None) -> None: + for item in children.get(parent, []): + if item["alias"] in seen: + continue + seen.add(item["alias"]) + out.append(item) + walk(item["alias"]) + + walk(None) + out.extend(i for i in items if i["alias"] not in seen) # 链成了环(不该有)也照列 + return out + + +def results(catalog: Mapping[str, Any]) -> list[tuple[str, dict[str, Any], dict[str, Any]]]: + """写作目录里的分析条目,按编号:[(A 编号, 条目, 结论)]。""" + found = [(str(alias), entry, dict(result)) for alias, entry in catalog.items() + if isinstance(entry, dict) and (result := catalog_result(entry)) is not None] + return sorted(found, key=lambda t: _alias_order(t[0])) + + +# -------------------------------------------------------------------------- +# 候选维度 +# -------------------------------------------------------------------------- + + +def _table_notes(tables: Mapping[str, Any], name: str) -> tuple[str, dict[str, Any]] | None: + """SQL 里写的表名在数据目录里的那一张:按 name_key 比,schema 前缀去掉再比一次。""" + wanted = {name_key(name), name_key(name.rsplit(".", 1)[-1])} + for table, notes in tables.items(): + if isinstance(notes, Mapping) and (name_key(str(table)) in wanted + or name_key(str(table).rsplit(".", 1)[-1]) in wanted): + return str(table), dict(notes) + return None + + +def _few_values(column: Mapping[str, Any]) -> bool: + """取值不多:码值表列出的取值不超过 CANDIDATE_MAX 个,或者标了已列全。""" + codes = column.get("codes") + if not isinstance(codes, Mapping) or codes.get("status") == "rejected": + return False + values = codes.get("value") + return codes.get("complete") is True or (isinstance(values, Mapping) and 0 < len(values) <= CANDIDATE_MAX) + + +def _candidates(table: str, notes: Mapping[str, Any], masked: set[str]) -> list[tuple[str, str, str]]: + """一张表上的候选维度:(表, 列, 叫法),按目录里的顺序。""" + out = [] + for column, body in (notes.get("columns") or {}).items(): + if not isinstance(body, Mapping) or name_key(str(column)) in masked: + continue + if _value(body.get("measure")) in _DIMENSION_MEASURES and _few_values(body): + label = _value(body.get("label")) + out.append((table, str(column), str(label) if isinstance(label, str) and label.strip() else str(column))) + return out + + +def _related(notes: Mapping[str, Any], tables: Mapping[str, Any]) -> list[tuple[str, dict[str, Any]]]: + """事实表关联的维度表:关系没被驳回、对面那张表目录里标了 dimension 或关系是多对一。""" + out = [] + for rel in notes.get("relations") or []: + if not isinstance(rel, Mapping) or rel.get("status") == "rejected" or not rel.get("to_table"): + continue + found = _table_notes(tables, str(rel["to_table"])) + if found and (_value(found[1].get("kind")) == "dimension" or rel.get("cardinality") == "many_to_one"): + out.append(found) + return out + + +def _fact_tables(names: list[str], tables: Mapping[str, Any]) -> list[tuple[str, dict[str, Any]]] | None: + """查询里的事实表;认不出的为 None。""" + found = [hit for name in names if (hit := _table_notes(tables, name))] + facts = [(t, n) for t, n in found if _value(n.get("kind")) in _FACT_KINDS] + if facts: + return facts + if len(names) == 1 and len(found) == 1 and _value(found[0][1].get("kind")) in (None, ""): + return found # 只读一张表、目录没标表类型:就是它 + return None + + +def _names(raw: Any) -> list[str]: + """遮罩列:列表,或者「a, b」这样的一段文字(同数据源设置里的写法)。""" + from app.data.engine import masked_columns + + return masked_columns({"mask_columns": raw}) if raw else [] + + +def _undecomposed(decomposes: list[dict[str, Any]], catalog: Mapping[str, Any], + sources: Mapping[str, Mapping[str, Any]] | None, + load: Callable[[str], Any]) -> tuple[list[str] | None, str | None]: + """(没拆过的候选维度的叫法, 核对不了时的说明)。""" + from app.engine.evidence import sql_tables + + if sources is None: + return None, NOTE_NO_CATALOG + if not decomposes: + return None, NOTE_NO_DECOMPOSE + queries = {str(e.get("artifact")): e for e in catalog.values() + if isinstance(e, dict) and e.get("kind") == "query" and e.get("artifact")} + pool: dict[tuple[str, str, str], str] = {} # (源, 表, 列 name_key) → 叫法,按目录里的顺序 + used: set[tuple[str, str, str]] = set() + for result in decomposes: + snapshots = [i.get("artifact") for i in result.get("inputs") or [] + if isinstance(i, Mapping) and i.get("role") in _DATA_ROLES and i.get("artifact")] + if not snapshots: + return None, NOTE_NO_QUERY + known: dict[str, tuple[str, str, str]] = {} # 这份拆解能对上的列:name_key → (源, 表, 列) + for artifact in snapshots: + try: + snapshot = load(str(artifact)) + except (ValueError, OSError): + snapshot = None + if not isinstance(snapshot, Mapping): + return None, NOTE_NO_QUERY + source = str(snapshot.get("source") or (queries.get(str(artifact)) or {}).get("source") or "") + facts_of = sources.get(source) if source else None + if facts_of is None: + return None, NOTE_NO_CATALOG + tables = facts_of.get("tables") or {} + if not tables: + return None, NOTE_NO_NOTES + masked = {name_key(str(c)) for c in [*_names(facts_of.get("masked")), *_names(snapshot.get("mask_columns"))]} + facts = _fact_tables(sql_tables(str(snapshot.get("sql") or "")), tables) + if facts is None: + return None, NOTE_NO_FACT + for table, notes in [*facts, *(r for t, n in facts for r in _related(n, tables))]: + for column in (notes.get("columns") or {}): + known.setdefault(name_key(str(column)), (source, table, name_key(str(column)))) + for _, column, label in _candidates(table, notes, masked): + pool.setdefault((source, table, name_key(column)), label) + for dim, label in zip(_dims(result), _dim_labels(result)): + hit = known.get(name_key(dim)) + if hit is None: + return None, f"候选维度核对不了:拆解按的「{label}」对不上数据目录里的列" + used.add(hit) + return [label for key, label in pool.items() if key not in used], None + + +# -------------------------------------------------------------------------- +# 组装 +# -------------------------------------------------------------------------- + + +def build(catalog: Mapping[str, Any], *, sources: Mapping[str, Mapping[str, Any]] | None = None, + load: Callable[[str], Any] | None = None) -> ScopeBlock | None: + """按写作目录里的分析条目算「分析范围」;目录里没有分析结论返回 None(不写这一项)。 + + sources 是 {数据源名: {"tables": {表: 数据目录 notes}, "masked": [遮罩列]}}(读不到目录时为 None,候选维度核对不了); + load 按 sha256 取回拆解的输入快照(缺省 artifact_store.load),认 SQL 用的是哪几张表。""" + if load is None: + from app.core.artifact_store import load as load_artifact + + load = load_artifact + found = results(catalog) + if not found: + return None + by_artifact = {str(e.get("artifact")): alias for alias, e, _ in found if e.get("artifact")} + items = {alias: _item(alias, r, _parent(r, by_artifact)) for alias, _, r in found} + ok = [(alias, r) for alias, _, r in found if r.get("status") == "ok"] + decomposes = [r for _, r in ok if r.get("op") == "decompose"] + excluded = [items[a] for a, r in ok + if (r.get("op") == "decompose" and _code(r) == "dispersed") + or (r.get("op") == "differ" and _code(r) == "no_evidence")] + tests = sum(1 for _, r in ok if r.get("op") == "differ") + try: + missing, note = _undecomposed([r for r in decomposes if _dims(r)], catalog, sources, load) + except Exception: # noqa: BLE001 - 分析范围是附带的说明,算不出来照实说核对不了,不挡报告 + logger.exception("分析范围的候选维度没有算成") + missing, note = None, "候选维度核对不了:核对时出了错" + return { + "phenomena": [items[a] for a, r in ok if r.get("op") in _PHENOMENA], + "decomposed": _chain([items[a] for a, r in ok if r.get("op") == "decompose"]), + "excluded": excluded, + "refused": [items[a] for a, _, r in found if r.get("status") != "ok"], + "not_decomposed": missing, + "note": note, + "tests": tests, + "corrected": None if not tests else tests == 1, + } + + +async def source_facts(names: Iterable[str], view: Any = None) -> dict[str, dict[str, Any]] | None: + """几个数据源(按名字)在这次运行的目录视图下的数据目录和遮罩列:{源名: {"tables": {表: notes}, "masked": [列]}}。 + 目录视图关掉的、读库出错的返回 None(候选维度核对不了);没有目录的源 tables 为空。""" + from sqlalchemy import select + + from app.data import catalog_view + from app.data.engine import masked_columns + from app.db.base import SessionLocal + from app.db.models import DataSource + + wanted = [n for n in dict.fromkeys(str(n) for n in names) if n] + view = catalog_view.CatalogView.parse(view) + if view.mode == "off": + return None + try: + async with SessionLocal() as session: + rows = list((await session.execute(select(DataSource).where(DataSource.name.in_(wanted)))).scalars()) \ + if wanted else [] + entries = await catalog_view.read_many(session, view, [r.id for r in rows]) + except Exception: # noqa: BLE001 - 目录是附带的说明,读不到照实说核对不了 + logger.exception("分析范围读取数据目录失败") + return None + return {row.name: {"tables": {t: e.notes for t, e in entries.get(row.id, {}).items()}, + "masked": masked_columns(row.options)} for row in rows} + + +async def scope_of(catalog: Mapping[str, Any], view: Any = None, *, + load: Callable[[str], Any] | None = None) -> ScopeBlock | None: + """报告节点用:读好拆解所用查询的数据源的目录,算「分析范围」。没有分析结论返回 None。""" + if load is None: + from app.core.artifact_store import load as load_artifact + + load = load_artifact + found = results(catalog) + if not found: + return None + sources: dict[str, dict[str, Any]] | None = None + try: + sources = await source_facts(_source_names(found, catalog, load), view) + except Exception: # noqa: BLE001 - 分析范围是附带的说明,读不到目录照实说核对不了,不挡报告 + logger.exception("分析范围没有读成数据目录") + return build(catalog, sources=sources, load=load) + + +def _source_names(found: list[tuple[str, dict[str, Any], dict[str, Any]]], catalog: Mapping[str, Any], + load: Callable[[str], Any]) -> list[str]: + """分析结论的输入快照来自哪几个数据源:写作目录里那次查询记的源名,没有就读快照。""" + names: list[str] = [] + for _, _, result in found: + for item in result.get("inputs") or []: + if not (isinstance(item, Mapping) and item.get("role") in _DATA_ROLES and item.get("artifact")): + continue + entry = next((e for e in catalog.values() if isinstance(e, dict) and e.get("kind") == "query" + and e.get("artifact") == item["artifact"]), None) + name = (entry or {}).get("source") + if not name: + try: + snapshot = load(str(item["artifact"])) + except (ValueError, OSError): + snapshot = None + name = snapshot.get("source") if isinstance(snapshot, Mapping) else None + if name: + names.append(str(name)) + return names + + +__all__ = ["CANDIDATE_MAX", "NOTE_NO_CATALOG", "NOTE_NO_DECOMPOSE", "NOTE_NO_FACT", "NOTE_NO_NOTES", "NOTE_NO_QUERY", "build", + "results", "scope_of", "source_facts"] diff --git a/backend/app/engine/autofix.py b/backend/app/engine/autofix.py index 2173e469..e97af135 100644 --- a/backend/app/engine/autofix.py +++ b/backend/app/engine/autofix.py @@ -1338,9 +1338,10 @@ def forbidden_changes(before: dict[str, Any], after: dict[str, Any], return reasons -#: 报告撰写节点三项设置从严到宽的次序:没写时运行时的缺省值(on_violation 没写时探索运行按 flag) +#: 报告撰写节点几项设置从严到宽的次序:没写时运行时的缺省值(on_violation 没写时探索运行按 flag,analysis_claims 没写是 +#: check) _REPORT_STRICT = {"numbers": ("strict", "strict"), "on_violation": ("fail", "flag"), - "claims": ("require_citation", "off")} + "claims": ("require_citation", "off"), "analysis_claims": ("strict", "check")} #: claims 从宽到严:off < require_citation < judge(在挂引用之外再请模型逐句裁判,不支持的按 on_unsupported #: 判档)。不在这里的写法不比较(validate 报 report.claims_invalid) _CLAIMS_ORDER = ("off", "require_citation", CLAIMS_JUDGE) diff --git a/backend/app/engine/compare.py b/backend/app/engine/compare.py index 6fb43657..61b7ed80 100644 --- a/backend/app/engine/compare.py +++ b/backend/app/engine/compare.py @@ -134,7 +134,8 @@ _CFG_KEYS: dict[str, frozenset[str]] = { "retrieve": frozenset({"query", "collection", "limit", "alpha", "rerank", "min_score", "assign_to"}), "metrics": frozenset({"metrics", "caliber", "caliber_version", "on_missing", "assign_to"}), "report": _MODEL_KEYS | {"numbers", "claims", "judge", "entities", "max_repairs", "system", "instructions", - "on_violation", "evidence_from", "metrics_from", "emit_message", "assign_to"}, + "on_violation", "evidence_from", "metrics_from", "emit_message", "assign_to", + "analysis_claims", "analysis_scope"}, } #: 只在调模型时才读的(_calls_model):条件分支让模型分类、结构校验让模型修复(默认开着)、知识检索用模型重排 _CFG_KEYS_IF: dict[str, frozenset[str]] = { diff --git a/backend/app/engine/evidence.py b/backend/app/engine/evidence.py index d1aeeecd..c77667e0 100644 --- a/backend/app/engine/evidence.py +++ b/backend/app/engine/evidence.py @@ -2869,10 +2869,17 @@ def _context(text: str, start: int, end: int) -> str: #: 粗体:**…** 或 __…__,里面可以有标记(标记里的下划线不算收尾,[[m:refund_rate]] 很常见) _BOLD = re.compile(r"(\*\*|__)(?P(?:\[\[" + _MARKER_GUARD + r"[^\[\]\n]*?\]\]|(?!\1)[^\n])+?)\1") #: 方向词、因果词:没有数字也没有引用的句子,含这些词才算结论。「同比」「环比」不在里面:它们只说明 -#: 跟谁比,本身不是涨跌;真正的比较结论还会带「增长」「下降」或者数字 +#: 跟谁比,本身不是涨跌;真正的比较结论还会带「增长」「下降」或者数字。 +#: 分析判断词(分析能力一轮,engine/analysis_claims 的说法表)也算:「主要来自」「集中在」「异常」「持续下降」「趋势」 +#: 「显著」,裁判优先判这类句子(judge.claim_priority)。「主要」后面是「包括、内容、分为、有、看」这类的是在列提纲, +#: 「持续关注」「持续跟进」是建议,「趋势图」「趋势如下」是在引出图表,「集中采购」「分散风险」说的不是数据,都不算 _DIRECTIONAL = re.compile( r"增长|增加|上升|提升|提高|上涨|下降|下滑|减少|降低|回落|下跌|反弹|超过|高于|低于|领先|落后|最高|最低" r"|最多|最少|来自|导致|因为|由于|带动|拉动|拖累|驱动|原因|归因|贡献|占比|翻倍|持平|波动" + r"|主要(?!包括|内容|分为|分成|有|看|从|是指|指|结论|发现|观点|工作|任务|目的|目标|问题|方面)" + r"|集中(?!采购|管理|处理|展示|讨论|培训)|异常|偏离" + r"|持续(?!关注|跟踪|跟进|观察|监控|推进|优化|改进|更新)|趋势(?![图表线如::])|显著|明显高于|明显低于|大幅|激增" + r"|骤降|暴跌|飙升|新高|新低|抵消|分散(?!注意|精力|风险|投资|采购)" r"|(? dict[str, Any]: """模型写的原文(带标记)→ 报告文档:渲染后的 markdown、块、句、片段、统计、违规。 entities=False(报告节点 entities: off):表名、字段名整层不管——不链接、不核对反引号, [[t:]] / [[c:]] 解析不了,原因是 ENTITIES_OFF_REASON。 absence=True(写作目录有省略):另查缺失断言(absence_claims),和句中的 [[see:]] 一样只在组装时查。 + analysis_claims(报告节点的分析说法核对,check / strict):文档顶层记下处置和说法表版本(engine/analysis_claims), + 判断词核对和裸数字一样在 verify_doc 里做,出口复核照它再核一遍。不给(None、off)的文档不记、不核,和以前一字不差。 masked({查询快照工件: 取自遮罩列的结果列},报告节点按数据源的遮罩算好交进来):另查直接引用了这些列的格子 (masked_cells),同样只在组装时查。没给的和以前一字不差。目录里值不给的指标(withhold_metrics 记了 masked 的)被引用 时也在这里记违规(masked_metrics),不靠这个参数:目录本身说了哪几个不给。 @@ -3217,9 +3227,13 @@ def compose_doc( # 没有它的(期 4 之前组装的)一律按原样展示。写在顶层、参与内容哈希,事后补不上:补了哈希就变,封存链就断 # cell_display:有单元格因为显示规则改了写法(ISO 日期时间)才记,记的是渲染得出这些格子的最低一版,复核照它渲染; # 没有的文档和以前一字不差 + # analysis_claims:报告节点要核分析说法时记下处置和说法表版本,复核照它走(只有带这一项的文档核判断词) + from app.engine import analysis_claims as said + doc: dict[str, Any] = { "schema": DOC_SCHEMA, "entity_syntax": snaps.syntax, "provenance": DOC_PROVENANCE, **({"cell_display": snaps.needed} if snaps.needed > 1 else {}), + **({said.DOC_FIELD: said.record(analysis_claims)} if analysis_claims in said.MODES else {}), "run_id": run_id, "node_id": node_id, "markdown": markdown, "source": source, "catalog": kept, "blocks": out_blocks, } @@ -3461,6 +3475,7 @@ def verify_doc( masks: list[tuple[int, int]] = [] # 引用渲染出来的字 syntax: list[tuple[int, int]] = [] # 结构片段:只涂符号,数字照查 owners: list[tuple[int, int, str, str]] = [] # (start, end, segment id, unit id) + cited_by: dict[int, list[str]] = {} # 每句按这次核对的引用算的依据(分析说法核对用) pos, tiled = 0, True for block, unit in iter_units(doc): stats["units"] += 1 @@ -3576,6 +3591,7 @@ def verify_doc( _unresolved_message("依据", f"see:{again['ref']}", again), ref=again["ref"], unit=unit.get("id"), span=list(unit.get("span") or []) or None)) + cited_by[id(unit)] = cited if kind == "claim" and not cited: stats["uncited_claims"] += 1 where = unit.get("span") @@ -3584,6 +3600,14 @@ def verify_doc( "text": markdown[where[0]:where[1]] if ok_span else ""}) if tiled and pos != len(markdown): violations.append(_violation("segment_mismatch", "正文末尾有一段不属于任何片段,文档可能被修改过")) + # 分析说法核对(engine/analysis_claims):只核记了这一项的文档,按记下的那一版说法表、这次核对的引用核。老文档不核, + # 统计也不多这个键。目录条目只带摘要的(存进文档的那份)按工件取回整份结论 + from app.engine import analysis_claims as said + + said_found = said.verify(doc, catalog, cited=cited_by, load=lambda alias, entry: snaps.analysis(alias, entry)[0]) + if said_found is not None: + violations.extend(said_found) + stats["analysis_claims"] = sum(1 for v in said_found if v["code"] in said.CODES) masks += _header_masks(list(doc.get("blocks") or []), catalog, snaps) + _name_masks(markdown, catalog, snaps) for token in _bare_numbers(markdown, masks, allow_numbers, syntax): diff --git a/backend/app/engine/governance.py b/backend/app/engine/governance.py index e2f389b7..9bad2d8f 100644 --- a/backend/app/engine/governance.py +++ b/backend/app/engine/governance.py @@ -18,6 +18,7 @@ from app.engine.schema import ( ValidationResult, _ancestors, _caliber_inputs, + analysis_claims_problem, claims_problem, contract_needs_metrics, judge_problems, @@ -324,7 +325,8 @@ def _lint_contract( # # G1 带契约的出口核对报告撰写节点的文档,成果字段的文字只能来自报告撰写节点 # G2 模型写的文字不绕过报告撰写节点直接流进出口(从图上追) -# G3 报告撰写节点写明 numbers: strict、on_violation: fail、claims: require_citation(或 judge,带上预算) +# G3 报告撰写节点写明 numbers: strict、on_violation: fail、claims: require_citation(或 judge,带上预算)、 +# analysis_claims: strict(分析能力一轮加的:判断词没挂对分析结论的句子重写后仍有的计入缺口) # G4 口径卡的输入不来自计算角色的沙箱代码 # G5 给口径卡供数的 agent 配 output_schema 并开 cite_fields(模型调用节点不能给口径卡供数) # @@ -332,13 +334,18 @@ def _lint_contract( # 下次发布才按这些规则查。受管级别挡住发布,已发布级别只给警告。 # -------------------------------------------------------------------------- -#: 报告撰写节点在受管级别里要写明的三项:(配置键, 要求的值, 为什么)。给人看的时候键和值都换成 -#: labels 里的界面叫法 +#: 报告撰写节点在受管级别里要写明的几项:(配置键, 要求的值, 为什么)。给人看的时候键和值都换成 +#: labels 里的界面叫法。自动修复、一键升级、按口径出具起草的报告节点都照这一份写(autofix、upgrade、ledger/certify)。 +#: analysis_claims 没写时运行时是 check(只标注、不影响档位),受管级别要写明 strict;已经发布的版本照常运行,下次发布才按 +#: 这一条查(和别的 G 规则一样只在发布、发布前检查时起作用) REPORT_POLICY = ( ("numbers", "strict", "没有出处的数字判为违规"), ("on_violation", "fail", "重写后仍有违规时节点失败,不带着问题出具"), ("claims", "require_citation", "未附依据的结论句计入缺口,出具按档位降档"), + ("analysis_claims", "strict", "判断词没挂对分析结论、原因没有依据的句子重写后仍有的计入缺口,出具按档位降档"), ) +#: 取值写错了由 validate 报(report.claims_invalid、report.analysis_claims_invalid),G3 不重复 +_POLICY_PROBLEMS = {"claims": claims_problem, "analysis_claims": analysis_claims_problem} #: 除了 REPORT_POLICY 里写的那个值,还认的更严的写法。claims: judge 在挂引用之外再请另一个模型按证据逐句 #: 裁判,不支持的按 on_unsupported 判档——比 require_citation 严,但要写预算(见 judge_budget_missing) REPORT_POLICY_ALSO: dict[str, tuple[str, ...]] = {"claims": (CLAIMS_JUDGE,)} @@ -669,8 +676,8 @@ def _lint_evidence(spec: GraphSpec, flag: Callable[..., None], *, strict: bool) loose = [] for key, want, why in REPORT_POLICY: value = _effective(spec, node, key) - if key == "claims" and claims_problem(value): - continue # 写了不认识的值,validate 的 report.claims_invalid 报 + if key in _POLICY_PROBLEMS and _POLICY_PROBLEMS[key](value): + continue # 写了不认识的值,validate 的 report.claims_invalid / analysis_claims_invalid 报 also = REPORT_POLICY_ALSO.get(key, ()) if value != want and value not in also: now = "当前未设置" if value in (None, "") else f"当前为「{option_label(key, value)}」" diff --git a/backend/app/engine/labels.py b/backend/app/engine/labels.py index 95e25941..4b1ea23e 100644 --- a/backend/app/engine/labels.py +++ b/backend/app/engine/labels.py @@ -59,6 +59,8 @@ FIELD_LABEL: dict[str, str] = { "instructions": "写作要求", "metrics_from": "指标来自", "numbers": "未引用的数字", "on_violation": "重写后仍有违规时", "max_repairs": "最多重写次数", "claims": "未附依据的结论句", "judge": "结论句裁判", "entities": "表名、字段名", + # 分析能力一轮:判断词要挂对应的分析结论(engine/analysis_claims)、文档末尾系统写的分析范围(engine/analysis_scope) + "analysis_claims": "分析说法核对", "analysis_scope": "分析范围", # 口径卡 "caliber_from": "口径卡来源", "caliber": "口径名称", "caliber_version": "口径版本", "metrics": "指标定义", "on_missing": "缺输入时", @@ -132,6 +134,8 @@ _OPTION_LABEL: dict[str, dict[str, str]] = { "on_violation": {"flag": "正常产出,并标注违规之处", "fail": "判为失败"}, "claims": {"off": "不参与出具判档", "require_citation": "计入缺口", "judge": "计入缺口并由模型逐句判断"}, "entities": {"link": "核对", "off": "不核对"}, + "analysis_claims": {"off": "不核对", "check": "重写一次后标出", "strict": "重写后仍有的计入缺口"}, + "analysis_scope": {"auto": "有分析结论时附上", "off": "不附"}, "evidence_role": {"source": "取数", "compute": "计算"}, "on_uncited": {"ignore": "仅标注,不计入缺口", "degrade": "计入缺口、出具降档", "withhold": "不予出具"}, "on_unsupported": {"degrade": "出具降档", "withhold": "不予出具"}, diff --git a/backend/app/engine/nodes/io.py b/backend/app/engine/nodes/io.py index 38ed2116..948ff862 100644 --- a/backend/app/engine/nodes/io.py +++ b/backend/app/engine/nodes/io.py @@ -4,6 +4,7 @@ import json import re from typing import Any +from app.analysis.contract import LEDGER_KIND from app.core.events import EventType from app.engine.context import NodeContext, NodeError from app.engine.expressions import ExpressionError, eval_expression @@ -236,6 +237,15 @@ def _apply_contract( ) unmatched = trace.unmatched if trace else [] + # 口径卡指标上的可比性(口径卡跨两份同形查询算环比、同比时自动查的):报告引用了的(引用模式按文档,别的按数字回指上 + # 的指标)、契约必需的指标两期不可比,记缺口降档;有条件可比的写进出具声明作标注 + required = {str(r) for r in contract.get("required") or []} + matched_ids = {str(h.get("metric")) for h in (trace.matched if trace else []) if h.get("metric")} + compared_gaps, comparability = _comparability( + [*(cited.get("cited_metrics") or []), + *(m for m in metrics if str(m.get("id")) in required | (set() if citations else matched_ids))]) + gaps.extend(compared_gaps) + # 同一条查询算出几个指标、报告又引用了它的格,只记一句(按出问题的那条查询归并,列出受影响的引用) titles = {n.id: n.title for n in ctx.run.spec.nodes} aliases: dict[str, str] = cited.get("aliases") or {} @@ -271,8 +281,9 @@ def _apply_contract( if isinstance(payload, dict) and payload.get("exhausted"): gaps.append(f"协作团队「{titles.get(node_id, node_id)}」用完 {payload.get('rounds', '?')} " "轮仍未完成,交付的是成员最后的回复") - # 上游节点自己报上来的缺口(双盲复算比不上、反方审稿的反驳没回应……):只会降档,不会升档 - gaps.extend(_upstream_issuance_gaps(state, ctx)) + # 上游节点自己报上来的缺口(双盲复算比不上、反方审稿的反驳没回应……):只会降档,不会升档。报告节点报的分析说法那一条, + # 引用模式下出口自己复核过、记了自己的缺口的不再重复收 + gaps.extend(_upstream_issuance_gaps(state, ctx, skip=cited.get("analysis_skip"))) tier = decide_tier( missing_required=missing_required, @@ -290,7 +301,7 @@ def _apply_contract( return _declare_citations(tier, cited, calibers=calibers, metrics=metrics, gaps=gaps, missing_required=missing_required, missing_expected=missing_expected, report_from=str(report_from), declared_at=datetime.now(timezone.utc), - ctx=ctx, sql_checks=sql_checks) + ctx=ctx, sql_checks=sql_checks, comparability=comparability) # 逐个数字的出处。以前只有一个计数,界面标不出「这个数来自哪个指标」 matched = [ @@ -311,6 +322,8 @@ def _apply_contract( "gaps": gaps, "declared_at": datetime.now(timezone.utc).isoformat(), **({"sql_checks": sql_checks} if sql_checks else {}), + # 指标的可比性(有条件可比的标注、不可比的同时在缺口里):只在有的时候带这个键 + **({"comparability": comparability} if comparability else {}), } ctx.emit( EventType.ISSUANCE, @@ -343,8 +356,9 @@ def _shown_text(fields: dict[str, Any]) -> str: return "\n".join(parts) -def _untraced_gaps(metrics: list[dict[str, Any]], ctx: NodeContext) -> list[str]: - """指标出具的缺口:输入没追到原始数据的指标,每个一句,说清停在哪个节点(engine/lineage 的认法)。""" +def _untraced(metrics: list[dict[str, Any]], ctx: NodeContext) -> list[dict[str, Any]]: + """输入没追到原始数据的指标(engine/lineage 的认法):[{metric, name, stops: [{path, node_id}], gap}]。gap 是缺口那一句, + 说清停在哪个节点。metrics 可以是契约收来的全部指标(指标出具),也可以只是报告引用的那几个(引用模式,D15)。""" from app.engine.lineage import untraced titles = {n.id: n.title for n in ctx.run.spec.nodes} @@ -357,11 +371,45 @@ def _untraced_gaps(metrics: list[dict[str, Any]], ctx: NodeContext) -> list[str] where = "、".join(dict.fromkeys( f"{s.get('path')}(停在「{titles.get(at, at or '未知来源')}」)" for s in stops[:3] for at in [str(s.get('node_id') or '').split('/', 1)[0]])) - out.append(f"指标「{m.get('name') or m.get('id')}」的输入没追到原始数据:{where}") + out.append({"metric": m.get("id"), "name": m.get("name") or m.get("id"), + "stops": [{"path": s.get("path"), "node_id": s.get("node_id")} for s in stops[:3]], + "gap": f"指标「{m.get('name') or m.get('id')}」的输入没追到原始数据:{where}"}) return out -def _upstream_issuance_gaps(state: GraphState, ctx: NodeContext) -> list[str]: +def _untraced_gaps(metrics: list[dict[str, Any]], ctx: NodeContext) -> list[str]: + """指标出具的缺口:输入没追到原始数据的指标,每个一句(_untraced)。""" + return [u["gap"] for u in _untraced(metrics, ctx)] + + +def _comparability(metrics: list[dict[str, Any]]) -> tuple[list[str], list[dict[str, Any]]]: + """口径卡指标上的可比性(contract.MetricComparability,口径卡跨两份同形查询算环比、同比时自动做的检查): + (缺口, 出具声明里的那一项)。metrics 是要看的指标(报告引用了的、契约必需的,调用方挑好):两期不可比的记缺口(降档, + 同 sql_check_failed),有条件可比的只标注。没有可比性记录的指标不在里面;同一条指标只看一次。""" + gaps: list[str] = [] + declared: list[dict[str, Any]] = [] + seen: set[int] = set() + for m in metrics: + mid = str(m.get("id") or "") if isinstance(m, dict) else "" + found = m.get("comparability") if mid else None + if not isinstance(found, dict) or id(m) in seen: + continue + seen.add(id(m)) + verdict = found.get("verdict") + if verdict not in ("conditional", "incomparable"): + continue + name = m.get("name") or mid + phrase = str(found.get("phrase") or "").strip() + declared.append({"metric": mid, "name": name, "verdict": verdict, "phrase": phrase, + "reasons": [str(r) for r in found.get("reasons") or [] if r], + **({"artifact": found["artifact"]} if found.get("artifact") else {})}) + if verdict == "incomparable": + gaps.append(f"指标「{name}」{phrase or '两期不可比'}") + return gaps, declared + + +def _upstream_issuance_gaps(state: GraphState, ctx: NodeContext, + skip: dict[str, set[str]] | None = None) -> list[str]: """上游节点产出里的 issuance_gaps(字符串列表),每条前面加上是哪个节点说的。 这是给「把关类」节点留的通用口子:节点觉得这次的结论不该完整出具(双盲复算两路对不上、 @@ -372,6 +420,9 @@ def _upstream_issuance_gaps(state: GraphState, ctx: NodeContext) -> list[str]: 只认这个成果节点的上游:另一条支路上的节点管不到这份成果。不是字符串、空白的条目跳过—— 这个键谁都能写(数据整形的 JSON 模板也行),写坏了只当没写,不能让出具崩掉。 + + skip:{节点 id: 不再收的那几条}。引用模式的出口自己复核过报告文档的分析说法、记了自己的缺口时,报告节点报上来的同一件事 + 不再重复收一条(_analysis_claims)。 """ from app.engine.labels import type_label @@ -388,7 +439,9 @@ def _upstream_issuance_gaps(state: GraphState, ctx: NodeContext) -> list[str]: continue kind = type_label(node.type) prefix = f"{kind}:" if node.title == kind else f"{kind}「{node.title}」:" - out.extend(prefix + gap.strip() for gap in reported if isinstance(gap, str) and gap.strip()) + dropped = (skip or {}).get(node.id) or set() + out.extend(prefix + gap.strip() for gap in reported + if isinstance(gap, str) and gap.strip() and gap not in dropped) return out @@ -418,12 +471,14 @@ def _check_citations( governed:受管级别的正式运行。可疑实体(名字哪里都找不到)只在这时按缺口降档,别处只标注。 """ from app.core.artifact_store import load + from app.engine import analysis_claims as said from app.engine.evidence import iter_units, ledger_enabled, resolve_ref, verify_doc from app.engine.nodes.report import report_catalog, report_entities out: dict[str, Any] = {"matched": [], "unmatched": [], "unresolved": [], "gaps": [], "doc_artifact": None, "stats": None, "claims_policy": None, "uncited": None, - "unsupported": None, "claims": None, "entities": None, "queries": {}, "aliases": {}} + "unsupported": None, "claims": None, "entities": None, "queries": {}, "aliases": {}, + "analysis": None, "analysis_skip": {}, "cited_metrics": [], "untraced": None} gaps = out["gaps"] spec = ctx.run.spec node = spec.node_map().get(report_from) @@ -458,7 +513,11 @@ def _check_citations( broken: list[str] = [] flagged: set[str] = set() suspicious: dict[str, list[dict[str, Any]]] = {"unknown_entity": [], "unverified_entity": []} + said_found: list[dict[str, Any]] = [] # 分析说法的违规(只有记了核对这一项的文档才有,_analysis_claims) for v in checked["violations"]: + if v["code"] in said.CODES: + said_found.append(v) + continue where = {k: v[k] for k in ("segment", "unit") if v.get(k)} if v.get("span"): where.update(start=v["span"][0], end=v["span"][1]) @@ -510,8 +569,12 @@ def _check_citations( if label: hit["caliber"] = label elif cite["kind"] == "cell": - # 查询单元格:Q1.r0.gmv(全局编号,和 doc.catalog 一致) + # 查询单元格:Q1.r0.gmv(全局编号,和 doc.catalog 一致);分析结论结果表的一格同一种写法(A3.r0.share) hit["cell"] = f"{cite['alias']}.r{cite['locator']['row']}.{cite['locator']['column']}" + elif cite["kind"] == LEDGER_KIND: + # 分析结论的具名标量([[a:A3.top_share]]):A3.top_share + key = (cite.get("locator") or {}).get("key") + hit["analysis"] = f"{cite['alias']}.{key}" if key else str(cite["alias"]) else: hit["input"] = cite["locator"].get("field") out["matched"].append({**hit, "segment": seg["id"], "unit": unit["id"], "start": start, "end": end, @@ -519,6 +582,16 @@ def _check_citations( _claims(out, contract, payload, evidence_on=ledger_enabled(ctx.run), governed=governed, uncited=checked.get("uncited") or [], doc=doc, title=node.title) + _analysis_claims(out, doc, payload, said_found, title=node.title, node_id=str(report_from)) + + # 报告引用的指标([[m:]] 片段和句末依据里的 m:):可比性按它们看(_apply_contract);输入追不到原始数据的,受管级别的 + # 正式运行记缺口(降档,和证据面板「追不到原始数据」的说法一致:代码节点自称取数也不能完整出具),其余写进出具声明 + out["cited_metrics"] = _cited_metrics(doc, catalog, state) + if stray := _untraced(out["cited_metrics"], ctx): + if governed: + gaps.extend(u["gap"] for u in stray) + out["untraced"] = {"metrics": [{k: u[k] for k in ("metric", "name", "stops")} for u in stray[:_LISTED]], + "counted": governed} mine = next((r for r in reports if r["node"].id == report_from), None) edited = mine["edited"] if mine else [] @@ -858,6 +931,70 @@ def _claims(out: dict[str, Any], contract: dict[str, Any], payload: dict[str, An } +#: 报告节点 analysis_claims 的三种处置,从松到严 +_ANALYSIS_ORDER = ("off", "check", "strict") + + +def _analysis_claims(out: dict[str, Any], doc: dict[str, Any], payload: Any, found: list[dict[str, Any]], *, + title: str, node_id: str) -> None: + """分析说法核对的出口独立复核(00-总方案 §3.5、D9):found 是 verify_doc 这次重新核出的说法违规(只有文档记了 + analysis_claims 那一项才核,老文档复核结果不变)。 + + 处置取报告文档记下的和报告节点产出里写的更严的那个:strict 有违规就记一条缺口(降档),报告节点报上来的同一条 + (产出的 analysis_gap)不再重复收;check 只写进出具声明作标注、不影响档位。要求 strict、文档里却没有核对记录的 + (不该发生),照实记一条缺口:出口替不了报告节点去核。结果放进 out["analysis"](出具声明的 analysis_claims), + strict 和有违规时才有。""" + from app.engine import analysis_claims as said + + found_mode = said.recorded(doc) + written = payload.get("analysis_claims") if isinstance(payload, dict) else None + modes = [m for m in (found_mode[0] if found_mode else None, written) if m in _ANALYSIS_ORDER] + mode = max(modes, key=_ANALYSIS_ORDER.index) if modes else None + if mode in (None, "off"): + return + if found_mode is None: + if mode == "strict": + out["gaps"].append(f"报告「{title}」要求严格核对分析说法,但文档中没有分析说法的核对记录,分析说法未核对") + return + counted = mode == "strict" + if found and counted: + out["gaps"].append(f"报告「{title}」有 {len(found)} 处分析说法未通过核对({said.summary(found)}):" + "判断要挂对应的分析结论并照判定写,原因要有知识库原话或运行输入作依据") + if isinstance(payload, dict) and isinstance(payload.get("analysis_gap"), str): + out["analysis_skip"] = {node_id: {payload["analysis_gap"]}} + if found or counted: + keep = ("code", "text", "claim", "op", "analyses", "unit", "segment", "span", "message", "context") + out["analysis"] = {"mode": mode, "count": len(found), "counts": said.counts(found), "counted": counted, + "violations": [{k: v[k] for k in keep if v.get(k) not in (None, "", [])} + for v in found[:_LISTED]]} + + +def _cited_metrics(doc: dict[str, Any], catalog: dict[str, Any], state: GraphState) -> list[dict[str, Any]]: + """报告引用了的指标([[m:]] 片段和句末 [[see:m:…]]):口径卡产出里的那一条(带 inputs、comparability),按引用的先后、 + 同一张卡的同一个指标只算一次。目录里认不出、卡的产出里找不到的跳过。""" + from app.engine.evidence import iter_units + + nodes = state.get("nodes") or {} + out: list[dict[str, Any]] = [] + seen: set[tuple[str, str]] = set() + for _, unit in iter_units(doc): + cites = [s.get("cite") for s in unit.get("segments") or [] if s.get("ref") and not s.get("auto")] + for cite in [*cites, *(unit.get("see") or [])]: + if not isinstance(cite, dict) or cite.get("kind") != "metric" or cite.get("status") != "resolved": + continue + entry = catalog.get(cite.get("alias")) or {} + card, mid = str(entry.get("node_id") or ""), str((entry.get("locator") or {}).get("metric") or "") + if entry.get("kind") != "metric" or not card or not mid or (card, mid) in seen: + continue + seen.add((card, mid)) + payload = nodes.get(card) + metric = next((m for m in (payload.get("metrics") or []) if isinstance(m, dict) and str(m.get("id")) == mid), + None) if isinstance(payload, dict) else None + if metric is not None: + out.append(metric) + return out + + def _cited_no_data(doc: dict[str, Any], catalog: dict[str, Any]) -> list[str]: """报告直接引用的格里,落在「查询区间里这张表没有数据」的列上的(查询快照的 no_data,data/coverage.py):按列一句缺口 「报告引用的 Q1「上周到访人数」:所依据的查询区间里这张表没有数据(…)」。读不出来的快照不算。""" @@ -895,37 +1032,51 @@ def _cited_queries(doc: dict[str, Any], catalog: dict[str, Any]) -> tuple[dict[s 单元格([[v:Q1.r0.gmv]],[[table:]] 展开后也是一格一格的引用)按查询数:一格写「Q1 第 1 行「gmv」」, 几格写「Q1 的 3 格」;只拿它当依据([[see:Q1]])的写「Q1(结论依据)」。出具契约据此判这些查询有没有通过 SQL 检查(issuance.sql_check_gaps)。 + + 分析结论按它的工件记(sql_problems.query_problems 顺着结论的输入找到查询):结果表的格同上(A3 第 1 行「share」); + 判定语、具名标量写「A3(判定语)」「A3「top_share」」,当依据([[see:A3]])的写「A3(结论依据)」——引用了一份分析 + 结论,它的输入查询上的问题照样计入缺口。 """ from app.engine.evidence import iter_units cells: dict[str, list[tuple[Any, Any]]] = {} + said: dict[str, list[str]] = {} # 分析结论的判定语、具名标量:{A 编号: [键或 None…]} support: list[str] = [] for _, unit in iter_units(doc): for seg in unit.get("segments") or []: cite = seg.get("cite") or {} - if cite.get("kind") == "cell" and cite.get("status") == "resolved" and cite.get("alias"): + if cite.get("status") != "resolved" or not cite.get("alias"): + continue + if cite.get("kind") == "cell": loc = cite.get("locator") or {} cells.setdefault(str(cite["alias"]), []) if (loc.get("row"), loc.get("column")) not in cells[str(cite["alias"])]: cells[str(cite["alias"])].append((loc.get("row"), loc.get("column"))) + elif cite.get("kind") == LEDGER_KIND: + keys = said.setdefault(str(cite["alias"]), []) + key = (cite.get("locator") or {}).get("key") + if key not in keys: + keys.append(key) for cite in unit.get("see") or []: alias = str((cite or {}).get("alias") or "") - if (catalog.get(alias) or {}).get("kind") == "query" and alias not in support: + if (catalog.get(alias) or {}).get("kind") in ("query", LEDGER_KIND) and alias not in support: support.append(alias) queries: dict[str, list[str]] = {} # 目录里全部查询的编号:合并查询的输入没被直接引用,缺口里也要写得出它是 Q 几 aliases = {str(e["artifact"]): str(e["alias"]) for e in catalog.values() if isinstance(e, dict) and e.get("kind") == "query" and e.get("artifact") and e.get("alias")} - for alias in [*cells, *(a for a in support if a not in cells)]: + for alias in dict.fromkeys([*cells, *said, *support]): artifact = (catalog.get(alias) or {}).get("artifact") if not isinstance(artifact, str) or not artifact: continue hit = cells.get(alias) or [] + refs = [] if len(hit) == 1 and isinstance(hit[0][0], int): - ref = f"{alias} 第 {hit[0][0] + 1} 行「{hit[0][1]}」" - else: - ref = f"{alias} 的 {len(hit)} 格" if hit else f"{alias}(结论依据)" - queries.setdefault(artifact, []).append(ref) + refs.append(f"{alias} 第 {hit[0][0] + 1} 行「{hit[0][1]}」") + elif hit: + refs.append(f"{alias} 的 {len(hit)} 格") + refs.extend(f"{alias}「{key}」" if key else f"{alias}(判定语)" for key in said.get(alias) or []) + queries.setdefault(artifact, []).extend(refs or [f"{alias}(结论依据)"]) return queries, aliases @@ -933,6 +1084,7 @@ def _declare_citations( tier: str, cited: dict[str, Any], *, calibers: list[dict[str, str]], metrics: list[dict[str, Any]], gaps: list[str], missing_required: list[str], missing_expected: list[str], report_from: str, declared_at: Any, ctx: NodeContext, sql_checks: list[dict[str, Any]] | None = None, + comparability: list[dict[str, Any]] | None = None, ) -> dict[str, Any]: """引用模式的 _issuance。旧字段一个不少(老前端照常显示),另加 mode、report、unresolved。""" # 节点 id 和报告文档、report.checked 事件上记的同一个(这次运行里的,子工作流里的带前缀) @@ -957,6 +1109,10 @@ def _declare_citations( **({"entities": cited["entities"]} if cited.get("entities") else {}), # 没通过 SQL 检查的查询(结构化):报告页据此在显眼处说明降档原因。没有就不加这个键 **({"sql_checks": sql_checks} if sql_checks else {}), + # 分析说法核对(strict,或者有违规时)、指标的可比性、报告引用的指标里追不到原始数据的:同样只在有的时候带 + **({"analysis_claims": cited["analysis"]} if cited.get("analysis") else {}), + **({"comparability": comparability} if comparability else {}), + **({"untraced": cited["untraced"]} if cited.get("untraced") else {}), } entities = cited.get("entities") ctx.emit( @@ -983,6 +1139,9 @@ def _declare_citations( **({"entities": {"unknown": (cited["stats"] or {}).get("unknown_entities", len(entities["unknown"])), "unverified": (cited["stats"] or {}).get("unverified_entities", len(entities["unverified"])), "counted": entities["counted"]}} if entities else {}), + # 分析说法:处置、几处、记没记缺口(名单只在出具声明里) + **({"analysis_claims": {k: cited["analysis"][k] for k in ("mode", "count", "counted")}} + if cited.get("analysis") else {}), ) return issuance diff --git a/backend/app/engine/nodes/report.py b/backend/app/engine/nodes/report.py index e21ff892..8cfa16b1 100644 --- a/backend/app/engine/nodes/report.py +++ b/backend/app/engine/nodes/report.py @@ -29,6 +29,16 @@ 不重复调用、不重复计费。写作调用不进 checkpoint,接着跑时会重写一稿——所以判定带着输入指纹, 对不上这一稿的不用 +分析能力一轮(docs/design/analysis-round/00-总方案.md §3.5–3.6):判定和数字一样由系统渲染,写作者只引用。 + +- 分析说法核对 analysis_claims:「主要来自」「异常」「持续上升」这类判断词要挂对应的分析结论、判定对得上,因果词要有 + 知识库原话或运行输入作依据(engine/analysis_claims,确定的词表 + 绑定,不调模型)。check(缺省,问数据也是它)交回写作者 + 重写一次(同句中的 [[see:]] 那一类,不按 max_repairs 反复),仍有的标在报告里、不影响档位;strict 按 max_repairs 重写, + 仍有的写进产出的 issuance_gaps,带契约的出口降档(受管级别要求 strict,门禁 G3);off 不核。说法违规都不让节点失败: + 不挡生成。文档顶层记下处置和说法表版本,出口复核照它独立再核一遍 +- 分析范围 analysis_scope:这次有分析结论、取值 auto(缺省)时,文档里另记系统写的「分析范围」(现象、拆过、排除、没拆、 + 检验,engine/analysis_scope),不进正文、不过裸数字和说法核对 + 出口契约复核(io.py)用 report_catalog 按同一套参数重建目录、独立重算,不信这里的自查。 """ from __future__ import annotations @@ -47,6 +57,7 @@ from langgraph.func import task from app.core.errors import describe_exception, not_configured from app.core.events import EventType from app.db.base import SessionLocal +from app.engine import analysis_claims as said from app.engine import judge as judging from app.engine.context import NodeContext, NodeError from app.engine.labels import field_label, option_label @@ -73,6 +84,9 @@ from app.engine.evidence import ( ) from app.engine.nodes.llm import _invoke_streaming, _model_spec, _report_call from app.engine.schema import ( + ANALYSIS_CLAIMS_DEFAULT, + ANALYSIS_CLAIMS_VALUES, + ANALYSIS_SCOPE_VALUES, CLAIMS_JUDGE, CLAIMS_VALUES, JUDGE_ON_UNSUPPORTED, @@ -80,6 +94,8 @@ from app.engine.schema import ( GraphSpec, NodeType, _ancestors, + analysis_claims_problem, + analysis_scope_problem, claims_problem, judge_problems, ) @@ -101,11 +117,14 @@ SOFT = frozenset({"unknown_entity", "unverified_entity"}) #: 写作目录有省略时的缺失断言(「没有查到」「数据缺失」:写作者没看全证据,结论依据不足,但数字和出处都核对过)。 #: 只剩这几类时不按 max_repairs 反复重写:重写一次没改掉,再写也多半一样,留在核对结果里标注 REWRITE_ONLY = frozenset({"inline_see", "absence_claim"}) +#: 分析说法的违规(判断词没挂对分析结论、因果没有依据):都不让节点失败。check 和 REWRITE_ONLY 一样只重写一次、仍有的 +#: 标注;strict 按 max_repairs 重写,仍有的写进出具缺口(_again、run_report 收尾) +ANALYSIS = said.CODES #: 重写一次就是多一次整篇的模型调用,写不对的模型多给几次也大多写不对 MAX_REPAIRS = 3 ROLE = ("你是报告撰写人。报告里的每个数字都由系统从证据里取出来、按口径卡的格式渲染;" - "你负责挑重点、组织结构、说清变化和原因。") + "你负责挑重点、组织结构、说清变化;有分析结论时说清变化来自哪里;原因只按证据写。") MARKUP_NUDGE = ("你上一条回复把工具调用写成了文字。报告撰写不调用任何工具:能用的数据都在上面的" "证据目录里,直接用引用标记写报告正文。") @@ -361,6 +380,19 @@ def report_claims(spec: GraphSpec, node: GraphNode) -> str: return value if isinstance(value, str) and value in CLAIMS else "off" +def report_analysis_claims(spec: GraphSpec, node: GraphNode) -> str: + """报告节点的分析说法核对:off / check / strict,没写是 check。写错的值画布校验就拦了,执行时节点也会报错,这里只把 + 认不出的当缺省。""" + value = _setting(spec, node, "analysis_claims", ANALYSIS_CLAIMS_DEFAULT) + return value if isinstance(value, str) and value in ANALYSIS_CLAIMS_VALUES else ANALYSIS_CLAIMS_DEFAULT + + +def report_analysis_scope(spec: GraphSpec, node: GraphNode) -> str: + """报告节点的分析范围:auto(缺省,这次有分析结论时写)/ off。""" + value = _setting(spec, node, "analysis_scope", "auto") + return value if isinstance(value, str) and value in ANALYSIS_SCOPE_VALUES else "auto" + + def report_judge(spec: GraphSpec, node: GraphNode) -> dict[str, Any]: """claims: judge 的子配置:节点上的 judge(没写取图级 defaults),写了的键原样保留——上限写 null 就是 不限,没写的键运行时取设置里的默认(judge.report_budget)。rewrite_once、on_unsupported 补上缺省 @@ -551,6 +583,8 @@ def _options(ctx: NodeContext) -> tuple[str, int]: entities = ctx.cfg("entities", "link") or "link" if entities not in ENTITIES: raise NodeError(ctx.node.id, _only("entities", ENTITIES, entities)) + if problem := analysis_claims_problem(ctx.cfg("analysis_claims")) or analysis_scope_problem(ctx.cfg("analysis_scope")): + raise NodeError(ctx.node.id, problem) raw = ctx.cfg("max_repairs", 1) try: repairs = int(raw) @@ -583,8 +617,16 @@ def _blocking(violations: list[dict[str, Any]], numbers: str) -> list[dict[str, def _fatal(blocking: list[dict[str, Any]]) -> list[dict[str, Any]]: - """要判失败的违规:重写之后还在的、不属于 REWRITE_ONLY 的。""" - return [v for v in blocking if v.get("code") not in REWRITE_ONLY] + """要判失败的违规:重写之后还在的、不属于 REWRITE_ONLY 的。分析说法的违规不判失败(不挡生成):check 只标注, + strict 记进出具缺口。""" + return [v for v in blocking if v.get("code") not in REWRITE_ONLY and v.get("code") not in ANALYSIS] + + +def _again(blocking: list[dict[str, Any]], analysis: str) -> list[dict[str, Any]]: + """值得按 max_repairs 反复重写的违规:要判失败的那些,加上 strict 下的分析说法违规。只剩别的(REWRITE_ONLY、check 下 + 的说法违规)时重写一次就停。""" + return [v for v in blocking if v.get("code") not in REWRITE_ONLY + and (v.get("code") not in ANALYSIS or analysis == "strict")] def _fail_advice(fatal: list[dict[str, Any]]) -> str: @@ -636,6 +678,8 @@ def _repair_request(violations: list[dict[str, Any]], failed_rule: str | None = f"{describe_violations(violations)}\n\n" "请重写整篇报告:所有数字都用引用标记写,只引用证据目录里有的指标和输入;" + (f"{failed_rule}" if failed_rule else "") + # 判断词没挂对分析结论、原因没有依据:怎么改在上面每一条里写了,这里再说一句总的 + + (said.ANALYSIS_REPAIR_PROMPT if any(v.get("code") in ANALYSIS for v in violations) else "") + "不要解释改了什么,只输出新的报告正文。" ) @@ -646,11 +690,15 @@ def run_today() -> date: def _messages(ctx: NodeContext, state: GraphState, writer: WriterCatalog, claims: str = "off", - failed: str | None = None) -> list[BaseMessage]: + failed: str | None = None, analysis: str | None = None) -> list[BaseMessage]: + """analysis 是这次要核分析说法时(check / strict)拼在写作规则后面的那一段(analysis_claims.rules_prompt:目录里有 + 分析结论和没有时各一种说法),不核时为 None、写作规则和以前一字不差。""" system = ctx.render_str(ctx.cfg("system", ""), state) instructions = ctx.render_str(ctx.cfg("instructions", ""), state).strip() \ or "根据下面的证据写一份简洁的报告,先总后分。" rules = f"{MARKER_RULES}\n{SEE_AND_CODE_RULES}\n{UNIT_RULE}\n{period_rule(run_today())}" + if analysis: + rules = f"{rules}\n{analysis}" if writer.guarded: # 写作者看不全证据(目录有省略、有来源的结构化结论为空):「没有查到」这类结论没有依据 rules = f"{rules}\n{ABSENCE_RULE}" @@ -771,6 +819,15 @@ async def run_report(state: GraphState, ctx: NodeContext) -> dict[str, Any]: # 结论句策略只对升级后发起的运行生效:升级前的运行(图里也不会有 claims)事件、产出一个字不加 evidence_on = ledger_enabled(ctx.run) claims = report_claims(spec, ctx.node) if evidence_on else "off" + # 分析说法核对、分析范围同样只对升级后发起的运行生效:升级前的运行写作规则、文档、产出一个字不加 + analysis = report_analysis_claims(spec, ctx.node) if evidence_on else "off" + scope = None + if evidence_on and report_analysis_scope(spec, ctx.node) == "auto" and said.results_of(catalog): + # 这次有分析结论:按写作目录里的结论和数据目录算一次「分析范围」,每一稿的文档都带着它(不进正文) + from app.data import catalog_view + from app.engine.analysis_scope import scope_of + + scope = await scope_of(catalog, catalog_view.of_run(ctx.run)) if evidence_on: # 升级前发起的运行没有查询条目,单元格无从谈起,也就不多查这一次 from app.engine.governance import governed_formal @@ -796,7 +853,8 @@ async def run_report(state: GraphState, ctx: NodeContext) -> dict[str, Any]: + ":已告诉写作模型照实说没有查到,不为它们写引用", failed=len(failed), any_query=any_query) messages = _messages(ctx, state, writer, claims, - _failed_section(failed, any_query=any_query) if failed else None) + _failed_section(failed, any_query=any_query) if failed else None, + said.rules_prompt(catalog) if analysis in said.MODES else None) started = time.perf_counter() spent: list[dict[str, Any]] = [] nudged = False @@ -830,16 +888,21 @@ async def run_report(state: GraphState, ctx: NodeContext) -> dict[str, Any]: # (_MaskedCells):只读正文里引用到的那几份快照 # 文档记这次运行里的节点 id(子工作流里的报告是「子工作流节点 id/…」):和它的 report.checked 事件、产出工件同一个 # id。证据接口、可验证报告、质询都拿文档上的 id 和事件上的比,对不上就判「疑似被修改」 - return await masked(compose_doc(_unfenced(raw), catalog, node_id=ctx.run.global_id(ctx.node.id), - run_id=ctx.run.run_id, - allow_numbers=allow, cells_allowed=cells, entities=entities, - absence=writer.trimmed)) + # 分析说法按 analysis 核(check / strict 时文档记下这一项,off 不记不核);分析范围是系统写的,每一稿都带同一份 + doc = await masked(compose_doc(_unfenced(raw), catalog, node_id=ctx.run.global_id(ctx.node.id), + run_id=ctx.run.run_id, + allow_numbers=allow, cells_allowed=cells, entities=entities, + absence=writer.trimmed, + analysis_claims=analysis if analysis in said.MODES else None)) + if scope is not None: + doc["analysis_scope"] = scope + return doc response, raw = await draft(messages) doc = await compose(raw) repairs = 0 while (blocking := _blocking(doc["violations"], numbers)) and repairs < max_repairs \ - and not (repairs and not _fatal(blocking)): + and not (repairs and not _again(blocking, analysis)): repairs += 1 ctx.emit(EventType.LOG, level="warn", code="report_repair", count=len(blocking), attempt=repairs, message=f"报告有 {len(blocking)} 处未通过核对({_named(blocking)})," @@ -886,11 +949,27 @@ async def run_report(state: GraphState, ctx: NodeContext) -> dict[str, Any]: columns=list(dict.fromkeys(str(v["column"]) for v in hits if v.get("column"))), message=f"{gaps[0]}。报告照常产出,这几处已标注,已记为缺口。" f"请在报告撰写节点的指令中去掉对{_masked_targets(hits)}的引用") + analysis_gap = None + if (left := [v for v in doc["violations"] if v.get("code") in ANALYSIS]) \ + and not (_fatal(blocking) and on_violation == "fail"): + # 重写之后还在:报告照常产出(不挡生成),这几处标在报告里;strict 另在产出里写一条缺口,成果节点设了出具契约、报告在 + # 它上游时照单收下、降档(io._upstream_issuance_gaps;引用模式的出口自己再核一遍,见 io._analysis_claims) + tried = f"已要求模型重写 {repairs} 次仍未改掉" if repairs else "未要求重写" + what = said.summary(left) + if analysis == "strict": + analysis_gap = f"报告有 {len(left)} 处分析说法未通过核对({what}:{_named(left)}),{tried}" + gaps.append(analysis_gap) + ctx.emit(EventType.LOG, level="warn", code="report_analysis_claims", count=len(left), mode=analysis, + texts=list(dict.fromkeys(str(v.get("text") or "") for v in left)), counts=said.counts(left), + message=f"报告有 {len(left)} 处分析说法未通过核对({what}:{_named(left)}),{tried}:" + "判断要挂对应的分析结论并照判定写,原因要有知识库原话或运行输入作依据。报告照常产出,这几处已标注" + + (",已记为缺口" if analysis_gap else "")) doc_artifact = await _store(doc, ctx) ctx.emit(EventType.REPORT_CHECKED, doc_artifact=doc_artifact, ok=not doc["violations"], stats=doc["stats"], violations=doc["violations"][:20], repairs=repairs, on_violation=on_violation, failed=bool(_fatal(blocking)) and on_violation == "fail", **({"claims": claims} if evidence_on else {}), + **({"analysis_claims": analysis} if evidence_on else {}), **({"judge": judgement} if judgement is not None else {})) if (fatal := _fatal(blocking)) and on_violation == "fail": blocking = fatal @@ -913,9 +992,13 @@ async def run_report(state: GraphState, ctx: NodeContext) -> dict[str, Any]: "model": model_id, "duration_ms": int((time.perf_counter() - started) * 1000), **({"claims": claims} if evidence_on else {}), + # 分析说法核对的处置:出口按它和文档里记的那一项判 strict 要不要记缺口(升级前的运行没有这个键) + **({"analysis_claims": analysis} if evidence_on else {}), **({"judge": judgement} if judgement is not None else {}), # 出口契约照单收下的缺口(只在有的时候带这个键:别的报告产出和以前一字不差) **({"issuance_gaps": gaps} if gaps else {}), + # 其中分析说法那一条:引用模式的出口自己复核过这份文档时以复核的为准,不再重复收这一条(io._analysis_claims) + **({"analysis_gap": analysis_gap} if analysis_gap else {}), # 写成「已遮罩」的指标:出口契约复核按它重建目录(report_catalog)。同上,只在有的时候带 **({"masked_metrics": withheld} if withheld else {}), } diff --git a/backend/app/engine/schema.py b/backend/app/engine/schema.py index 447591cb..e2e036b0 100644 --- a/backend/app/engine/schema.py +++ b/backend/app/engine/schema.py @@ -806,6 +806,13 @@ CLAIMS_VALUES = (*REPORT_CLAIMS, CLAIMS_JUDGE) JUDGE_KEYS = ("provider", "model", "max_claims", "max_cost_usd", "timeout_s", "rewrite_once", "on_unsupported") #: 证据相矛盾时正式运行怎么判档:degrade 降档(默认)/ withhold 不予出具。探索运行只标注 JUDGE_ON_UNSUPPORTED = ("degrade", "withhold") +#: 报告撰写节点的分析说法核对(analysis_claims,docs/design/analysis-round/00-总方案.md §3.5、engine/analysis_claims): +#: off 不核;check(缺省,问数据也是它)判断词没挂对分析结论的句子交回写作者重写一次、仍有的标出,不影响出具档位; +#: strict 按最多重写次数重写,仍有的计入出具缺口(受管级别要求它,门禁 G3) +ANALYSIS_CLAIMS_VALUES = ("off", "check", "strict") +ANALYSIS_CLAIMS_DEFAULT = "check" +#: 报告文档里系统写的「分析范围」(analysis_scope,engine/analysis_scope):auto(缺省)这次有分析结论时写;off 不写 +ANALYSIS_SCOPE_VALUES = ("auto", "off") #: 「没有指定模型」那条提示的编号。节点(或全图默认)点名了接入、而那个接入本身不存在或已停用时,它和接入那条问题 #: 互相矛盾(一条说照常执行、一条说会失败),接口层读了接入表以后按编号去掉它(provider_refs.quiet_unset_model) @@ -829,6 +836,24 @@ def claims_problem(value: Any) -> str | None: return (f"「{field_label('claims')}」只能选{'、'.join(allowed[:-1])}或{allowed[-1]},当前为「{value}」") +def _choice_problem(key: str, value: Any, allowed: tuple[str, ...]) -> str | None: + """一个只能在几个取值里选的报告节点配置写错了的说法(没写的不算错,按缺省)。""" + if value in (None, "") or (isinstance(value, str) and value in allowed): + return None + names = [f"「{option_label(key, v)}」" for v in allowed] + return f"「{field_label(key)}」只能选{'、'.join(names[:-1])}或{names[-1]},当前为「{value}」" + + +def analysis_claims_problem(value: Any) -> str | None: + """analysis_claims 的取值有什么问题,没问题返回 None。校验和报告撰写节点执行时报的是同一句话。""" + return _choice_problem("analysis_claims", value, ANALYSIS_CLAIMS_VALUES) + + +def analysis_scope_problem(value: Any) -> str | None: + """analysis_scope 的取值有什么问题,没问题返回 None。""" + return _choice_problem("analysis_scope", value, ANALYSIS_SCOPE_VALUES) + + def _positive(value: Any, *, integer: bool = False) -> bool: if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or value <= 0: return False @@ -887,6 +912,11 @@ def _check_report_claims(node: GraphNode, spec: GraphSpec, result: ValidationRes value = effective("claims") if problem := claims_problem(value): result.add(problem, node_id=node.id, field="claims", code="report.claims_invalid") + # 分析说法核对、分析范围:写错了执行时报告节点照样报这一句 + if problem := analysis_claims_problem(effective("analysis_claims")): + result.add(problem, node_id=node.id, field="analysis_claims", code="report.analysis_claims_invalid") + if problem := analysis_scope_problem(effective("analysis_scope")): + result.add(problem, node_id=node.id, field="analysis_scope", code="report.analysis_scope_invalid") if value != CLAIMS_JUDGE: return judge = effective("judge") diff --git a/backend/app/plain.py b/backend/app/plain.py index 0058ff60..350d2667 100644 --- a/backend/app/plain.py +++ b/backend/app/plain.py @@ -80,7 +80,9 @@ PLAIN: dict[str, Plain] = { "governed.text_bypass": Plain( "模型写的文字绕过了报告直接进了成果", "这些文字里的数和表名都没法追溯。", _A, "改由报告撰写节点来写,成果取报告正文。"), "governed.report_policy": Plain( - "报告的核对规则不够严", "受管级别要求报告用最严的核对规则。", _A, "把报告撰写节点的核对规则调到最严。"), + "报告的核对规则不够严", + "受管级别要求报告用最严的核对规则:数字要有出处、结论句要挂依据,「主要来自」「异常」这类判断要挂对分析结论。", _A, + "把报告撰写节点的核对规则调到最严,分析说法核对也设为严格。"), "governed.judge_budget": Plain( "模型裁判没设金额上限", "裁判的花费不能沿用默认值,要事先说清。", _Y, "写一个每份报告的裁判金额上限,或明确选择不限。"), "governed.caliber_compute_input": Plain( diff --git a/backend/app/seed.py b/backend/app/seed.py index 389af049..213bfba2 100644 --- a/backend/app/seed.py +++ b/backend/app/seed.py @@ -266,9 +266,9 @@ TEMPLATES: list[dict[str, Any]] = [ "expression": "cell(nodes.fetch, 0, 'refund_cnt') / cell(nodes.fetch, 0, 'order_cnt')" " if cell(nodes.fetch, 0, 'order_cnt') else None"}, ]), - # 受管出具要求报告撰写节点写明最严的三项(发布门禁 G3),模板照着写,拿来就能发布成受管 + # 受管出具要求报告撰写节点写明最严的几项(发布门禁 G3,含分析说法核对设为严格),模板照着写,拿来就能发布成受管 _n("write", "report", "报告撰写", metrics_from=["caliber"], - numbers="strict", on_violation="fail", claims="require_citation", + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict", system="你是周报撰写人:结论先行,只写有数据支撑的判断。", instructions="为 {{ input.week }} 写一份简短的周报:先用一两句话总结本周," "再分点说销售额、订单、客单价和退款的变化。"), diff --git a/backend/tests/test_analysis_claims.py b/backend/tests/test_analysis_claims.py new file mode 100644 index 00000000..5a5b9a8c --- /dev/null +++ b/backend/tests/test_analysis_claims.py @@ -0,0 +1,465 @@ +"""分析说法核对(engine/analysis_claims.py,细案 01 §9):判断词要挂对应的分析结论、判定对得上,因果词要有依据。 + +- 说法表:每类的判断词认得出,常见的非判断写法(持续关注、异常订单、相当于、数据异常)不算;「大幅」收进异常类,看清它在 + 常见写法里的表现 +- 否定:判断词前 4 个字以内(跳过填充词)有否定的翻到反面类;「不但」「不少」不是否定 +- 绑定:类要的 op 在这句的依据里出现、判定对得上;点名的段在 subjects 里(全半角归一);拖累、拉动看那一段的方向; + 新高新低看 caveat;「连续」看末尾连续的期数;挂了算不了的结论算对不上 +- 来源与因果的分界:因果词点名的是拆解的段 → 按来源核;不是 → 按因果核;推测说法、知识库原话、运行输入豁免因果 +- 不扫:判定语(a:)、知识库原话(q:)、别的引用渲染出来的字、标题、代码块、表头 +- 文档:只有记了这一项的文档在复核时核,老文档复核结果不变;记了认不出的版本记 bad_schema +""" +from __future__ import annotations + +import pytest + +from app.analysis.testing import fake_result +from app.engine import analysis_claims as ac +from app.engine import evidence +from app.engine.evidence import build_catalog, compose_doc, make_eid, verify_doc + + +def hits(text: str) -> list[tuple[str, str, str | None]]: + return [(h.claim, h.word, h.direction) for h in ac.scan(text)] + + +def claims(text: str) -> list[str]: + return [h.claim for h in ac.scan(text)] + + +def said(text: str, *analyses: str, results=None, **sentence) -> list[dict]: + """一句话、挂了 analyses 这几份结论:违规清单。""" + return ac.check_sentence(ac.Sentence(text=text, analyses=list(analyses), **sentence), results or {}) + + +def codes(found: list[dict]) -> list[str]: + return [v["code"] for v in found] + + +# -------------------------------------------------------------------------- +# 说法表:每类认得出、常见的非判断写法不算 +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("text, claim", [ + ("下降主要来自华东。", "source"), ("增长主要由线上贡献。", "source"), ("下降集中在华东、华北。", "source"), + ("绝大部分来自线下。", "source"), ("华东拖累了整体。", "source"), ("线上带动了增长。", "source"), + ("华东贡献最大。", "source"), ("下降主要是华东下滑造成的。", "source"), + ("变化分散在各地区。", "dispersed"), ("各地区都在下降。", "dispersed"), ("各渠道普遍下滑。", "dispersed"), + ("全面下降。", "dispersed"), + ("华东和华南此消彼长。", "offset"), ("两者互相抵消。", "offset"), + ("退款率上升来自结构变化。", "mix"), ("这是结构性的上升。", "mix"), + ("本周销售额异常下降。", "anomaly"), ("取消单激增。", "anomaly"), ("订单数骤降。", "anomaly"), + ("销售额明显偏离往常。", "anomaly"), ("超出过去 12 周的常规波动范围。", "anomaly"), + ("销售额明显高于正常水平。", "anomaly"), ("波动剧烈。", "anomaly"), + ("本周创历史新高。", "record"), ("销售额创新高。", "record"), ("前所未有。", "record"), + ("在常规波动范围内。", "normal"), ("属于正常波动。", "normal"), ("并不异常。", "normal"), + ("线上销售额持续上升。", "trend"), ("呈上升趋势。", "trend"), ("一路走低。", "trend"), ("稳步增长。", "trend"), + ("连续三周下降。", "trend"), ("连续下滑。", "trend"), + ("没有明显的上升或下降趋势。", "no_trend"), ("上升趋势不明显。", "no_trend"), ("基本平稳。", "no_trend"), + ("西南的退款率显著高于华东。", "differ"), ("两组差异明显。", "differ"), + ("两组差异不大。", "no_diff"), ("两组没有明显差异。", "no_diff"), ("两个渠道的退款率相当。", "no_diff"), + ("由于促销结束,销售额下降。", "causal"), ("受天气影响,客流下降。", "causal"), ("增长得益于新客。", "causal"), +]) +def test_every_class_is_recognized(text, claim): + assert claim in claims(text), hits(text) + + +@pytest.mark.parametrize("text", [ + "建议持续关注华东的退款。", # 「持续」后面不是涨跌:建议 + "异常订单 12 单。", # 「异常」后面是名词:业务分类 + "本周没有发现数据异常。", # 数据质量 + "系统无异常。", + "销售额相当于上周的两倍。", # 「相当于」 + "华东的销售额相当高。", # 「相当」是副词 + "这个问题引起关注。", # 「引起关注」不是因果 + "主导地位没有变。", # 「主导地位」 + "降幅较大。", # 不是「大幅」 + "整体平稳。", # 只收「基本平稳」:宁可漏报 + "趋势值得关注。", # 「趋势」不带涨跌 + "华东销售额下降,华南销售额上升。", # 只陈述数字和变化 +]) +def test_ordinary_wording_is_not_a_judgement(text): + assert ac.scan(text) == [] + + +def test_the_longest_reading_wins_where_two_overlap(): + # 「超出正常范围」是异常,不是正常;「没有明显的上升或下降趋势」是无趋势,不是上升趋势 + assert claims("超出正常范围。") == ["anomaly"] + assert claims("没有明显的上升或下降趋势。") == ["no_trend"] + assert claims("下降主要由华东造成。") == ["source", "causal"] + + +def test_the_word_carries_its_direction(): + assert [h.run for h in ac.scan("连续三周下降,持续下降。")] == [True, False] + assert hits("取消单激增。") == [("anomaly", "激增", "up")] + assert hits("订单数骤降。") == [("anomaly", "骤降", "down")] + assert hits("线上销售额持续上升。") == [("trend", "持续上升", "up")] + assert hits("本周销售额异常下降。")[0][2] == "down" # 方向在判断词后面 + assert hits("销售额下降,属于异常。")[0][2] is None # 分句里没有涨跌 + assert hits("华东拖累了整体。")[0][2] == "down" and hits("线上带动了增长。")[0][2] == "up" + + +# -------------------------------------------------------------------------- +# 「大幅」:收进异常类,看清它在常见写法里的表现 +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("text, direction", [ + ("本周销售额大幅增长。", "up"), ("订单数大幅下降。", "down"), ("退款大幅度减少。", "down"), + ("客单价大幅提升,订单数基本不变。", "up"), ("销售额同比大幅下滑。", "down"), +]) +def test_dafu_is_an_anomaly_claim_with_the_direction_of_its_verb(text, direction): + [(claim, word, got)] = hits(text) + assert claim == "anomaly" and word.startswith("大幅") and got == direction + + +@pytest.mark.parametrize("text", ["销售额大幅领先华南。", "幅度较大。", "大幅的促销海报已经撤下。"]) +def test_dafu_without_a_change_verb_is_not_counted(text): + assert ac.scan(text) == [] + + +def test_dafu_needs_a_baseline_outside_the_band_in_the_same_direction(): + up = fake_result("baseline", None, "outside_band", direction="up") + down = fake_result("baseline", None, "outside_band", direction="down") + normal = fake_result("baseline", None, "within_band", direction="up") + text = "本周销售额大幅增长。" + assert codes(said(text)) == [ac.UNCITED] # 没挂:要挂波动基线 + assert said(text, "A1", results={"A1": up}) == [] + [miss] = said(text, "A1", results={"A1": down}) + assert miss["code"] == ac.MISMATCH and "方向" in miss["message"] + [miss] = said(text, "A1", results={"A1": normal}) + assert miss["code"] == ac.MISMATCH and "常规波动范围内" in miss["message"] + + +# -------------------------------------------------------------------------- +# 否定 +# -------------------------------------------------------------------------- + + +@pytest.mark.parametrize("text, claim", [ + ("并未出现明显异常。", "normal"), # 否定隔着「出现明显」 + ("本周没有出现异常。", "normal"), + ("不在正常范围内。", "anomaly"), + ("不属于正常波动。", "anomaly"), + ("没有显著高于华东。", "no_diff"), + ("并非主要来自华东。", "source_not"), + ("并不分散。", "source"), + ("没有持续上升。", "no_trend"), +]) +def test_a_negation_flips_to_the_opposite_class(text, claim): + assert claims(text) == [claim] + + +@pytest.mark.parametrize("text", ["不但大幅增长,", "不少门店大幅下滑。", "无论是否大幅增长,"]) +def test_words_that_only_look_negative_do_not_flip(text): + assert claims(text) == ["anomaly"] + + +def test_negated_causes_and_records_are_left_alone(): + assert ac.scan("并非由于促销。") == [] and ac.scan("并非历史新高。") == [] + + +def test_a_negated_source_needs_the_named_segment_outside_the_main_sources(): + driver = fake_result() # 主要来自华东 + assert said("下降并非主要来自华南。", "A1", results={"A1": driver}) == [] + [miss] = said("下降并非主要来自华东。", "A1", results={"A1": driver}) + assert miss["code"] == ac.MISMATCH and "华东" in miss["message"] + dispersed = fake_result(verdict="dispersed") + assert said("下降并非主要来自某一个地区。", "A1", results={"A1": dispersed}) == [] + + +# -------------------------------------------------------------------------- +# 绑定 +# -------------------------------------------------------------------------- + + +def test_the_required_op_must_be_among_the_evidence(): + baseline = fake_result("baseline", None, "outside_band") + [v] = said("下降主要来自华东。", "A1", results={"A1": baseline}) + assert v["code"] == ac.UNCITED and v["op"] == "decompose" and v["claim"] == "source" and v["analyses"] == ["A1"] + # 有好几个时任一个对得上就算对 + assert said("下降主要来自华东。", "A1", "A2", results={"A1": baseline, "A2": fake_result()}) == [] + + +def test_named_segments_must_be_among_the_subjects(): + concentrated = fake_result(verdict="concentrated", subjects=[["华东"], ["华北"]]) + assert said("下降集中在华东、华北。", "A1", results={"A1": concentrated}) == [] + [miss] = said("下降集中在华东、华南。", "A1", results={"A1": concentrated}) + assert miss["code"] == ac.MISMATCH and "不是华南" in miss["message"] + # 别的分句里提到的段不算点名 + assert said("下降主要来自华东,华南基本持平。", "A1", results={"A1": fake_result()}) == [] + + +def test_ascii_names_need_word_boundaries_but_chinese_neighbours_are_fine(): + result = fake_result(subjects=[["AB"]]) + result["table"]["rows"][0][0] = "AB" + result["table"]["rows"][1][0] = "A" + assert said("下降主要来自AB店。", "A1", results={"A1": result}) == [] + assert said("下降主要来自XAB。", "A1", results={"A1": result}) == [], "XAB 不是点名 AB,也没点名别的段" + assert codes(said("下降主要来自A。", "A1", results={"A1": result})) == [], "一个字的名字不认" + + +def test_named_segments_are_matched_across_full_and_half_width(): + result = fake_result(subjects=[["A店"]]) + result["table"]["rows"][0][0] = "A店" + assert said("下降主要来自A店。", "A1", results={"A1": result}) == [] + assert codes(said("下降主要来自华北。", "A1", results={"A1": result})) == [ac.MISMATCH] + + +def test_a_dispersed_verdict_cannot_back_a_main_source(): + [miss] = said("下降主要来自华东。", "A3", results={"A3": fake_result(verdict="dispersed")}) + assert miss["code"] == ac.MISMATCH and miss["text"] == "主要来自" + assert "A3" in miss["message"] and "分散在各地区" in miss["message"] + assert "[[a:A3]]" in miss["for_model"] and "不能写「主要来自华东」" in miss["for_model"] + + +def test_drag_and_pull_follow_the_direction_of_the_segment(): + up = fake_result(direction="up") + up["table"]["rows"][0][3] = "120" # 华东 +120 + assert said("华东带动了增长。", "A1", results={"A1": up}) == [] + [miss] = said("华东拖累了整体。", "A1", results={"A1": up}) + assert miss["code"] == ac.MISMATCH and "上升" in miss["message"] + assert said("华东拖累了整体。", "A1", results={"A1": fake_result()}) == [] # 华东 −120 + + +def test_a_drag_outside_the_main_sources_counts_when_it_is_a_large_share(): + # 整体上涨、华南是主要来源,华东下跌拖累了涨幅:华东的变化占总变化过半(绝对值)也算拖累 + result = fake_result(subjects=[["华南"]], direction="up") + result["table"]["rows"][0][3:6] = ["-120", "-0.1463", "-1.5"] + assert said("华东拖累了涨幅。", "A1", results={"A1": result}) == [] + result["table"]["rows"][0][5] = "-0.2" + assert codes(said("华东拖累了涨幅。", "A1", results={"A1": result})) == [ac.MISMATCH] + + +def test_records_need_the_caveat_in_the_same_direction(): + high = fake_result("baseline", None, "far_outside_band", direction="up", + caveats=[{"code": "record_high", "text": "本期是历史最高"}]) + assert said("本周创历史新高。", "A1", results={"A1": high}) == [] + assert codes(said("本周创历史新低。", "A1", results={"A1": high})) == [ac.MISMATCH] + plain = fake_result("baseline", None, "outside_band", direction="up") + assert codes(said("本周创历史新高。", "A1", results={"A1": plain})) == [ac.MISMATCH] + + +def test_trends_check_the_direction_and_runs_check_the_length(): + rising = fake_result("trend", None, "rising", direction="up", values={"run_length": "4", "run_direction": "up"}) + assert said("线上销售额持续上升。", "A1", results={"A1": rising}) == [] + assert codes(said("线上销售额持续下降。", "A1", results={"A1": rising})) == [ac.MISMATCH] + assert said("线上销售额连续四周上升。", "A1", results={"A1": rising}) == [] + short = fake_result("trend", None, "rising", direction="up", values={"run_length": "2", "run_direction": "up"}) + [miss] = said("线上销售额连续上升。", "A1", results={"A1": short}) + assert miss["code"] == ac.MISMATCH and "连续" in miss["message"] + flat = fake_result("trend", None, "no_trend", direction=None) + assert said("没有明显的上升或下降趋势。", "A1", results={"A1": flat}) == [] + assert codes(said("线上销售额持续上升。", "A1", results={"A1": flat})) == [ac.MISMATCH] + + +def test_differences_check_the_verdict_and_the_order_of_the_two_groups(): + differs = fake_result("differ", "rate", "differs", subjects=[["西南"], ["华东"]], direction="up") + assert said("西南的退款率显著高于华东。", "A1", results={"A1": differs}) == [] + assert said("华东的退款率显著低于西南。", "A1", results={"A1": differs}) == [] + [miss] = said("西南的退款率显著低于华东。", "A1", results={"A1": differs}) + assert miss["code"] == ac.MISMATCH and "西南高于华东" in miss["message"] + nothing = fake_result("differ", "rate", "no_evidence", subjects=[["西南"], ["华东"]], direction=None) + assert said("两组差异不大。", "A1", results={"A1": nothing}) == [] + assert codes(said("西南的退款率显著高于华东。", "A1", results={"A1": nothing})) == [ac.MISMATCH] + + +def test_a_structure_claim_needs_a_ratio_decomposition(): + [miss] = said("退款率上升来自结构变化。", "A1", results={"A1": fake_result()}) + assert miss["code"] == ac.MISMATCH and "结构变化要挂变化拆解(比率)" in miss["message"] + mix = fake_result(mode="ratio", verdict="mix_driven") + assert said("退款率上升来自结构变化。", "A1", results={"A1": mix}) == [] + + +def test_offsets_need_the_caveat(): + assert codes(said("华东和华南此消彼长。", "A1", results={"A1": fake_result()})) == [ac.MISMATCH] + offset = fake_result(caveats=[{"code": "offset", "text": "下降的段合计 −120"}]) + assert said("华东和华南此消彼长。", "A1", results={"A1": offset}) == [] + + +def test_a_refused_conclusion_backs_nothing(): + refused = fake_result("baseline", None, None, status="refused", reason_code="history_short") + [miss] = said("本周销售额异常下降。", "A1", results={"A1": refused}) + assert miss["code"] == ac.MISMATCH and "没有做成" in miss["message"] and "历史只有 5 期" in miss["message"] + + +def test_uncited_advice_points_at_a_conclusion_that_exists(): + [v] = said("下降主要来自华东。", results={"A2": fake_result()}) + assert "[[see:A2]]" in v["for_model"] and "[[a:A2]]" in v["for_model"] + [v] = said("下降主要来自华东。") + assert "这次没有变化拆解的结论" in v["for_model"] and "只写各段各自的变化" in v["for_model"] + # 结构变化只推荐比率拆解;算不了的结论不推荐 + [v] = said("这是结构性的上升。", results={"A2": fake_result(), "A3": fake_result(mode="ratio", verdict="both")}) + assert "[[see:A3]]" in v["for_model"] + [v] = said("下降主要来自华东。", results={"A2": fake_result(status="refused")}) + assert "[[see:A2]]" not in v["for_model"] + + +def test_one_violation_per_class_and_clause(): + found = said("由于促销结束导致下降。") + assert codes(found) == [ac.CAUSAL] and found[0]["text"] == "由于" + assert "「由于促销结束导致下降」" in found[0]["message"] + assert codes(said("由于促销结束,下降;由于天气,客流减少。")) == [ac.CAUSAL, ac.CAUSAL] + + +# -------------------------------------------------------------------------- +# 来源与因果 +# -------------------------------------------------------------------------- + + +def test_a_cause_naming_a_segment_of_the_decomposition_is_checked_as_a_source(): + driver = fake_result() + assert said("下降主要由华东造成。", "A1", results={"A1": driver}) == [] + assert said("增长得益于华东。", "A1", results={"A1": fake_result(direction="up")}) == [] + [miss] = said("下降是华南造成的。", "A1", results={"A1": driver}) + assert miss["code"] == ac.MISMATCH and miss["claim"] == "source" + + +def test_a_cause_outside_the_decomposition_needs_its_own_evidence(): + [v] = said("由于促销结束导致下降。", "A1", results={"A1": fake_result()}) + assert v["code"] == ac.CAUSAL and v["claim"] == "causal" and "op" not in v + assert "可能与…有关,待核实" in v["for_model"] + + +@pytest.mark.parametrize("sentence", [ + {"text": "可能与促销结束有关,待核实。"}, + {"text": "下降或许是由于促销结束。"}, + {"text": "疑似由于促销结束导致下降。"}, + {"text": "由于促销结束导致下降。", "quoted": True}, + {"text": "由于促销结束导致下降。", "inputs": True}, + {"text": "由于数据只到 10 月 16 日,本周不完整。"}, + {"text": "由于样本少,差异不能下结论。"}, +]) +def test_guesses_quotes_inputs_and_data_caveats_are_not_unsupported_causes(sentence): + assert ac.check_sentence(ac.Sentence(**sentence), {}) == [] + + +# -------------------------------------------------------------------------- +# 文档:哪里不扫、怎么挂、版本 +# -------------------------------------------------------------------------- + + +def a_entry(alias: str, result: dict) -> dict: + artifact = "a" * 63 + alias[-1] + return {"alias": alias, "kind": "analysis", "artifact": artifact, "eid": make_eid("analysis", artifact, {}), + "locator": {}, "result": result} + + +def catalog(**analyses) -> dict: + out = build_catalog(nodes={"caliber": { + "kind": "metric_set", "caliber": "周报口径", "caliber_version": "v2", "artifact": "f" * 64, + "metrics": [{"id": "gmv", "name": "销售额", "value": 45678.5, "unit": "元", "decimals": 1}]}}, + inputs={"promo": "满减"}) + out.update({alias: a_entry(alias, result) for alias, result in analyses.items()}) + return out + + +def found(doc: dict) -> list[dict]: + return [v for v in doc["violations"] if v["code"] in ac.CODES] + + +def test_a_doc_records_the_mode_and_lexicon_only_when_asked(): + raw = "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv]]" + doc = compose_doc(raw, catalog(), analysis_claims="check") + assert doc[ac.DOC_FIELD] == {"mode": "check", "lexicon": ac.LEXICON_VERSION} + [v] = found(doc) + assert v["code"] == ac.UNCITED and doc["markdown"][slice(*v["span"])] == "主要来自" + assert v["unit"] and v["segment"] and v["context"] == "本周销售额 45,678.5元,下降主要来自华东。" + assert doc["stats"]["analysis_claims"] == 1 + # 没要求(off、老调用):文档一字不差,统计也不多这个键 + for mode in (None, "off"): + plain = compose_doc(raw, catalog(), analysis_claims=mode) + assert ac.DOC_FIELD not in plain and found(plain) == [] and "analysis_claims" not in plain["stats"] + + +def test_old_documents_verify_exactly_as_before(): + raw = "本周销售额 [[m:gmv]],下降主要来自华东,由于促销结束。[[see:m:gmv]]" + old = compose_doc(raw, catalog()) + assert verify_doc(old, catalog()) == verify_doc(compose_doc(raw, catalog()), catalog()) + assert verify_doc(old, catalog())["violations"] == [] and "analysis_claims" not in verify_doc(old, catalog())["stats"] + new = compose_doc(raw, catalog(), analysis_claims="strict") + again = verify_doc(new, catalog()) + assert [v["code"] for v in again["violations"]] == [ac.UNCITED, ac.CAUSAL] + assert again["stats"]["analysis_claims"] == 2 and again["violations"] == new["violations"] + + +def test_an_unrecognized_record_is_reported_and_checked_with_the_current_lexicon(): + doc = compose_doc("下降主要来自华东。", catalog(), analysis_claims="check") + doc[ac.DOC_FIELD] = {"mode": "check", "lexicon": 99} + checked = verify_doc(doc, catalog()) + assert [v["code"] for v in checked["violations"]] == ["bad_schema", ac.UNCITED] + assert "分析说法核对规则" in checked["violations"][0]["message"] + + +def test_system_rendered_phrases_quotes_headings_and_code_are_not_scanned(): + doc = {"markdown": "", "blocks": [ + {"type": "heading", "units": [{"id": "u0", "kind": "heading", "segments": [ + {"id": "s0", "kind": "text", "text": "下降主要来自华东", "span": [0, 8]}]}]}, + {"type": "code", "units": [{"id": "u1", "kind": "code", "segments": [ + {"id": "s1", "kind": "text", "text": "-- 异常订单激增", "span": [8, 17]}]}]}, + {"type": "paragraph", "units": [{"id": "u2", "kind": "claim", "segments": [ + {"id": "s2", "kind": "value", "text": "销售额下降 194 万,主要来自华东(-120 万,占 62%)", "ref": "a:A1"}, + {"id": "s3", "kind": "text", "text": "。售后说「"}, + {"id": "s4", "kind": "quote", "text": "退款主要集中在东区,由于物流延误", "ref": "q:K1|退款主要集中在东区,由于物流延误", + "state": "deterministic"}, + {"id": "s5", "kind": "text", "text": "」。"}]}]}, + {"type": "table", "units": [{"id": "u3", "kind": "connective", "loc": {"row": -1, "col": 0}, "segments": [ + {"id": "s6", "kind": "text", "text": "是否异常"}]}]}, + ]} + assert ac.check_doc(doc, catalog()) == [] + # 同一句换成写作者自己写的字就核 + doc["blocks"][2]["units"][0]["segments"][0] = {"id": "s2", "kind": "text", "text": "销售额下降,主要来自华东"} + assert codes(ac.check_doc(doc, catalog())) == [ac.UNCITED] + + +def test_rendered_values_name_segments_but_are_not_judgement_words(): + # [[v:…]] 渲染出来的「华东」能点名,渲染出来的「异常」不是写作者下的判断 + doc = {"markdown": "", "blocks": [{"type": "paragraph", "units": [{"id": "u0", "kind": "claim", "cites": ["A1"], + "segments": [ + {"id": "s0", "kind": "text", "text": "下降主要来自", "span": [0, 6]}, + {"id": "s1", "kind": "value", "text": "华南", "ref": "v:Q1.r1.region", "span": [6, 8]}, + {"id": "s2", "kind": "text", "text": ",状态为", "span": [8, 12]}, + {"id": "s3", "kind": "value", "text": "异常", "ref": "v:Q1.r1.status", "span": [12, 14]}]}]}]} + [miss] = ac.check_doc(doc, {"A1": a_entry("A1", fake_result())}) + assert miss["code"] == ac.MISMATCH and "不是华南" in miss["message"] and miss["span"] == [2, 6] + + +def test_compose_and_verify_bind_the_sentence_to_its_see_marker(): + cat = catalog(A1=fake_result()) + ok = compose_doc("销售额 [[m:gmv]],下降主要来自华东。[[see:A1]]", cat, analysis_claims="check") + assert found(ok) == [] and verify_doc(ok, cat)["violations"] == [] + bad = compose_doc("销售额 [[m:gmv]],下降主要来自华南。[[see:A1]]", cat, analysis_claims="check") + [miss] = found(bad) + assert miss["code"] == ac.MISMATCH and miss["analyses"] == ["A1"] + # 复核按这次重新解析的引用算,不信文档里记的 cites:依据删掉了就是没挂 + tampered = compose_doc("销售额 [[m:gmv]],下降主要来自华东。[[see:A1]]", cat, analysis_claims="check") + tampered["blocks"][0]["units"][0]["see"] = [] + assert [v["code"] for v in verify_doc(tampered, cat)["violations"]] == [ac.UNCITED] + + +def test_inputs_and_quotes_in_the_same_sentence_support_a_cause(): + doc = compose_doc("由于本周有 [[i:promo]] 活动,销售额 [[m:gmv]]。[[see:m:gmv]]", catalog(), analysis_claims="check") + assert found(doc) == [] + doc = compose_doc("由于本周有活动,销售额 [[m:gmv]]。[[see:m:gmv,i:promo]]", catalog(), analysis_claims="check") + assert found(doc) == [] + doc = compose_doc("由于本周有活动,销售额 [[m:gmv]]。[[see:m:gmv]]", catalog(), analysis_claims="check") + assert codes(found(doc)) == [ac.CAUSAL] + + +def test_the_prompt_rules_depend_on_whether_there_are_conclusions(): + assert ac.rules_prompt(catalog()) == ac.ANALYSIS_NONE_PROMPT + assert ac.rules_prompt(catalog(A1=fake_result())) == ac.ANALYSIS_RULES_PROMPT + assert "只陈述数字和变化" in ac.ANALYSIS_NONE_PROMPT and "待核实" in ac.ANALYSIS_NONE_PROMPT + assert "[[a:A1]]" in ac.ANALYSIS_RULES_PROMPT + + +def test_judgement_words_make_a_sentence_a_claim_for_the_judge(): + from app.engine.judge import claim_priority + + doc = compose_doc("华东异常。\n\n下面主要看三个方面。\n\n建议持续关注。\n\n近 8 周的趋势图如下:", catalog()) + kinds = {doc["markdown"][slice(*u["span"])]: (u["kind"], claim_priority(u, b, doc["markdown"])) + for b, u in evidence.iter_units(doc)} + assert kinds["华东异常。"] == ("claim", 2) + assert kinds["下面主要看三个方面。"][0] == "connective" and kinds["建议持续关注。"][0] == "connective" + assert kinds["近 8 周的趋势图如下:"][0] == "connective", "引出图表的话不算判断" diff --git a/backend/tests/test_analysis_claims_operators.py b/backend/tests/test_analysis_claims_operators.py new file mode 100644 index 00000000..19af5e57 --- /dev/null +++ b/backend/tests/test_analysis_claims_operators.py @@ -0,0 +1,191 @@ +"""说法核对挂真算子算出来的结论(app/analysis,第 1 波 W1-a):判定、点名的段、方向、新高新低、连续、抵消、结构、差异的两组、 +算不了,都按算子真给的形状核(tests/analysis_samples 的样例:虚构零售库 shop)。再经组装和复核走一遍:判定语 [[a:A1]] 和 +具名标量 [[a:A1.键]] 整段不扫,[[see:A1]] 当依据。""" +from __future__ import annotations + +import pytest + +from app.engine import analysis_claims as ac +from app.engine.evidence import build_catalog, compose_doc, make_eid, verify_doc +from tests.analysis_samples import analyze, fixed_prober, snap + +SQL = "SELECT region, week, SUM(amount) AS gmv FROM orders GROUP BY region, week" +TYPES = {"region": "text", "week": "text", "gmv": "number"} +WEEKLY = [["华东", "2026-W41", 820], ["华东", "2026-W42", 700], ["华北", "2026-W41", 600], ["华北", "2026-W42", 560], + ["华南", "2026-W41", 700], ["华南", "2026-W42", 666], ["西南", "2026-W41", 100], ["西南", "2026-W42", 100]] + + +async def additive(rows=WEEKLY, **params): + s = snap("Q2", SQL, ["region", "week", "gmv"], rows, types=TYPES) + return await analyze("decompose", "additive", snaps=[s], query="Q2", by=["region"], period="week", + base="2026-W41", target="2026-W42", measure="gmv", label="销售额", **params) + + +def weekly_rows(base: dict, target: dict) -> list[list]: + return [[k, "2026-W41", v] for k, v in base.items()] + [[k, "2026-W42", v] for k, v in target.items()] + + +def said(text: str, **results) -> list[str]: + """一句话挂了 results 这几份结论:违规的代码。""" + return [v["code"] for v in ac.check_sentence(ac.Sentence(text=text, analyses=list(results)), results)] + + +async def test_an_additive_driver_backs_its_segment_and_nothing_else(): + a1 = await additive() + assert a1["verdict"] == {"code": "driver", "subjects": [["华东"]], "direction": "down"} + assert said("销售额下降主要来自华东。", A1=a1) == [] + assert said("华东拖累了整体。", A1=a1) == [] + assert said("销售额下降主要来自华南。", A1=a1) == [ac.MISMATCH] + assert said("华北带动了增长。", A1=a1) == [ac.MISMATCH], "华北下降、占比不到一半,不能说带动" + assert said("各地区普遍下降。", A1=a1) == [ac.MISMATCH] + + +async def test_a_dispersed_change_backs_only_dispersion(): + a1 = await additive(weekly_rows({"华东": 100, "华北": 100, "华南": 100, "西南": 100}, + {"华东": 75, "华北": 75, "华南": 75, "西南": 75})) + assert a1["verdict"]["code"] == "dispersed" + assert said("销售额下降分散在各地区。", A1=a1) == [] + assert said("销售额下降主要来自华东。", A1=a1) == [ac.MISMATCH] + + +async def test_a_flat_total_with_opposite_segments_backs_an_offset(): + a1 = await additive(weekly_rows({"华东": 500, "华南": 500, "华北": 300}, {"华东": 550, "华南": 450, "华北": 300})) + assert a1["verdict"]["code"] == "flat" + assert said("华东和华南此消彼长。", A1=a1) == [] + assert said("销售额基本持平,主要来自华东。", A1=a1) == [ac.MISMATCH] + + +async def test_a_ratio_decomposition_backs_structure_and_its_main_source(): + s = snap("Q1", "SELECT channel, week, SUM(refund_flag) AS refunds, COUNT(*) AS orders FROM orders GROUP BY 1, 2", + ["channel", "week", "refunds", "orders"], + [["线上", "W41", 50, 500], ["线上", "W42", 90, 1000], ["线下", "W41", 10, 1000], ["线下", "W42", 4, 500]]) + a1 = await analyze("decompose", "ratio", snaps=[s], query="Q1", by="channel", period="week", base="W41", + target="W42", numerator="refunds", denominator="orders", label="退款率") + assert a1["verdict"] == {"code": "mix_driven", "subjects": [["线上"]], "direction": "up"} + assert said("退款率上升来自结构变化。", A1=a1) == [] + assert said("退款率上升主要来自结构变化,线上占比变大。", A1=a1) == [], "判定语就是这么说的" + assert said("退款率上升主要来自线下。", A1=a1) == [ac.MISMATCH] + + +async def test_a_factor_decomposition_names_its_factor(): + s = snap("Q1", "SELECT week, SUM(amount) AS gmv, COUNT(*) AS orders, ROUND(AVG(amount), 2) AS aov FROM orders " + "GROUP BY week", ["week", "gmv", "orders", "aov"], + [["W41", 10000, 100, 100], ["W42", 15000, 150, 100]]) + a1 = await analyze("decompose", "factor", snaps=[s], query="Q1", period="week", base="W41", target="W42", + product="gmv", factors=["orders", "aov"], label="销售额") + assert a1["verdict"]["code"] == "driver" + [[factor]] = a1["verdict"]["subjects"] + assert said(f"销售额增长主要来自{factor}的增长。", A1=a1) == [] + other = next(r[0] for r in a1["table"]["rows"] if r[0] != factor) + assert said(f"销售额增长主要来自{other}。", A1=a1) == [ac.MISMATCH] + + +NOISE = [100, 102, 98, 101, 99, 103, 100, 97, 102, 101, 99, 100, 98, 103, 101, 100, 99, 102, 100] +SERIES_SQL = "SELECT DATE(order_date, 'weekday 0', '-6 days') AS week, COUNT(*) AS orders FROM orders GROUP BY 1" + + +def weeks(values): + from datetime import date, timedelta + + start = date(2026, 10, 12) - timedelta(days=7 * (len(values) - 1)) + return [[(start + timedelta(days=7 * i)).isoformat(), v] for i, v in enumerate(values)] + + +async def series(op: str, values, **params): + probe = fixed_prober({("orders", "order_date"): ("2025-01-01", "2026-10-20")}) + s = snap("Q1", SERIES_SQL, ["week", "orders"], weeks(values), types={"week": "text", "orders": "number"}) + return await analyze(op, snaps=[s], probe=probe, query="Q1", period="week", measure="orders", label="订单数", + **params) + + +async def test_a_baseline_backs_anomalies_records_and_normal_swings_in_the_right_direction(): + far = await series("baseline", NOISE + [70]) + assert far["verdict"] == {"code": "far_outside_band", "subjects": [], "direction": "down"} + assert said("订单数本周骤降。", A1=far) == [] + assert said("订单数本周大幅下降,创历史新低。", A1=far) == [] + assert said("订单数本周异常增长。", A1=far) == [ac.MISMATCH] + assert said("订单数创历史新高。", A1=far) == [ac.MISMATCH] + assert said("订单数属于正常波动。", A1=far) == [ac.MISMATCH] + within = await series("baseline", NOISE + [101]) + assert within["verdict"]["code"] == "within_band" + assert said("订单数属于正常波动,并未出现明显异常。", A1=within) == [] + assert said("订单数异常。", A1=within) == [ac.MISMATCH] + + +async def test_a_trend_backs_its_direction_and_runs_only_when_long_enough(): + rising = await series("trend", [100 + 3 * i + (i % 3) for i in range(12)]) + assert rising["verdict"]["code"] == "rising" and rising["values"]["run_direction"] == "up" + assert said("订单数持续上升。", A1=rising) == [] + assert said("订单数已连续多周上升。", A1=rising) == [] + assert said("订单数持续下降。", A1=rising) == [ac.MISMATCH] + assert said("订单数没有明显趋势。", A1=rising) == [ac.MISMATCH] + short = dict(rising, values={**rising["values"], "run_length": "2"}) + assert said("订单数连续上升。", A1=short) == [ac.MISMATCH] + + +async def test_a_difference_backs_the_higher_group_in_either_order(): + rates = snap("Q1", "SELECT region, SUM(refund_flag) AS refunds, COUNT(*) AS orders FROM orders GROUP BY region", + ["region", "refunds", "orders"], [["西南", 80, 1000], ["华东", 40, 1000]]) + differs = await analyze("differ", "rate", snaps=[rates], query="Q1", by="region", numerator="refunds", + denominator="orders", label="退款率") + assert differs["verdict"] == {"code": "differs", "subjects": [["西南"], ["华东"]], "direction": "up"} + assert said("西南的退款率显著高于华东。", A1=differs) == [] + assert said("华东的退款率明显低于西南。", A1=differs) == [] + assert said("西南的退款率显著低于华东。", A1=differs) == [ac.MISMATCH] + small = snap("Q1", "SELECT region, SUM(refund_flag) AS refunds, COUNT(*) AS orders FROM orders GROUP BY region", + ["region", "refunds", "orders"], [["西南", 2, 40], ["华东", 5, 230]]) + nothing = await analyze("differ", "rate", snaps=[small], query="Q1", by="region", numerator="refunds", + denominator="orders", label="退款率") + assert nothing["verdict"]["code"] == "no_evidence" + assert said("两地的退款率差异不大。", A1=nothing) == [] + assert said("西南的退款率显著高于华东。", A1=nothing) == [ac.MISMATCH] + + +async def test_a_refused_baseline_backs_no_judgement(): + short = await series("baseline", [100, 102, 98, 70]) + assert short["status"] == "refused" and short["verdict"] is None and short["reason_code"] == "history_short" + [miss] = ac.check_sentence(ac.Sentence(text="订单数本周异常下降。", analyses=["A1"]), {"A1": short}) + assert miss["code"] == ac.MISMATCH and "没有做成" in miss["message"] + + +# -------------------------------------------------------------------------- +# 经组装和复核:判定语、具名标量不扫,[[see:A1]] 当依据 +# -------------------------------------------------------------------------- + + +@pytest.fixture +async def driver_catalog(): + a1 = await additive() + catalog = build_catalog(nodes={"caliber": { + "kind": "metric_set", "caliber": "周报口径", "caliber_version": "v2", "artifact": "f" * 64, + "metrics": [{"id": "gmv", "name": "销售额", "value": 2026, "unit": "元"}]}}) + artifact = "e" * 64 + catalog["A1"] = {"alias": "A1", "kind": "analysis", "artifact": artifact, "eid": make_eid("analysis", artifact, {}), + "locator": {}, "op": "decompose", "mode": "additive", "status": "ok", "item": "drop", + "inputs": [], "result": a1} + return catalog + + +@pytest.mark.parametrize("raw", [ + "[[a:A1]]。", + "[[a:A1]]:下降主要来自华东。", + "华东占变化的 [[a:A1.top_share|pct]],下降主要来自华东。[[see:A1]]", + "下降主要来自华东。[[see:A1.r0]]", + "下降主要来自华东。[[see:a:A1]]", +]) +def test_phrases_and_scalars_are_not_scanned_and_see_markers_bind(driver_catalog, raw): + doc = compose_doc(raw, driver_catalog, analysis_claims="check") + assert [v for v in doc["violations"] if v["code"] in ac.CODES] == [], doc["violations"] + assert [v for v in verify_doc(doc, driver_catalog)["violations"] if v["code"] in ac.CODES] == [] + + +def test_a_contradicting_sentence_next_to_the_phrase_is_caught(driver_catalog): + doc = compose_doc("[[a:A1]]。下降主要来自华南。[[see:A1]]", driver_catalog, analysis_claims="check") + [miss] = [v for v in doc["violations"] if v["code"] in ac.CODES] + assert miss["code"] == ac.MISMATCH and miss["analyses"] == ["A1"] and miss["unit"] and miss["segment"] + assert doc["markdown"][slice(*miss["span"])] == "主要来自" + # 存进文档的目录只留摘要:按工件取不回结论时只能当作没挂(交给复核的是重建的整份目录,这里看清楚退路) + stored = {k: v for k, v in doc["catalog"]["A1"].items() if k != "result"} + assert ac.results_of({"A1": stored}) == {} + assert ac.results_of({"A1": stored}, lambda alias, entry: driver_catalog["A1"]["result"])["A1"]["verdict"]["code"] \ + == "driver" diff --git a/backend/tests/test_analysis_scope.py b/backend/tests/test_analysis_scope.py new file mode 100644 index 00000000..d9e956e9 --- /dev/null +++ b/backend/tests/test_analysis_scope.py @@ -0,0 +1,206 @@ +"""报告文档里系统写的「分析范围」(engine/analysis_scope.py,00-总方案 §3.6,契约 contract.ScopeBlock)。 + +- 现象、拆过(按下钻链)、排除(分散、差异可能只是样本波动)、算不了、检验次数 +- 没拆:候选维度确定地从数据目录算——拆解所用查询的事实表上标成属性、状态、不遮罩、取值不多的列,加上它关联的维度表; + 拆解按的列对不上目录、读不到目录、认不出事实表时只说核对不了,不乱列 +- agent 写的假设不进这一段 +""" +from __future__ import annotations + +import sqlite3 +import uuid + +import pytest + +from app.analysis.testing import fake_result +from app.data import catalog as data_catalog +from app.data.catalog import make_item +from app.data.catalog_view import CatalogView +from app.data.introspect import introspect +from app.db.base import SessionLocal +from app.db.models import DataSource +from app.engine import analysis_scope as scope +from app.engine.evidence import make_eid +from tests.fixtures.sources import drop_source + +SQL = "SELECT o.region, o.week, SUM(o.amount) AS gmv FROM orders o JOIN stores s ON s.id = o.store_id GROUP BY 1, 2" +SNAP = "1" * 64 +SNAPSHOTS = {SNAP: {"source": "shop", "sql": SQL, "columns": ["region", "week", "gmv"], "rows": []}} + + +def codes(*values: str, complete: bool = False) -> dict: + item = make_item({v: "" for v in values}, "profile", "verified") + return {**item, "complete": True} if complete else item + + +def column(label: str, measure: str | None = None, codes_item: dict | None = None) -> dict: + out = {"label": make_item(label, "human")} + if measure: + out["measure"] = make_item(measure, "human") + if codes_item: + out["codes"] = codes_item + return out + + +NOTES = { + "orders": { + "kind": make_item("fact", "human"), + "columns": { + "region": column("地区", "attribute", codes("华东", "华南", "华北", "西南")), + "channel": column("渠道", "attribute", codes("线上", "线下")), + "status": column("订单状态", "status", codes("1", "2", "9", complete=True)), + "member_level": column("会员等级", "attribute"), # 没有码值:取值多不多说不清 + "customer_id": column("客户编号", "identifier", codes("c1", "c2")), + "phone": column("手机号", "attribute", codes("1", "2")), # 遮罩列 + "amount": column("实收金额", "flow"), + "week": column("周", "attribute", codes(*(f"W{i}" for i in range(60)))), # 取值太多 + }, + "relations": [{"id": "r1", "columns": ["store_id"], "to_table": "stores", "to_columns": ["id"], + "cardinality": "many_to_one", "source": "fk", "status": "verified"}], + }, + "stores": { + "kind": make_item("dimension", "human"), + "columns": {"store_type": column("门店类型", "attribute", codes("旗舰", "社区")), + "city": column("城市", "attribute", codes("上海", "杭州"))}, + }, +} +SOURCES = {"shop": {"tables": NOTES, "masked": ["phone"]}} + + +def entry(alias: str, result: dict) -> dict: + artifact = "a" * 63 + alias[-1] + return {"alias": alias, "kind": "analysis", "artifact": artifact, "eid": make_eid("analysis", artifact, {}), + "locator": {}, "result": result} + + +def data(snapshot: str = SNAP) -> list[dict]: + return [{"ref": "Q1", "artifact": snapshot, "role": "data", "columns": ["region", "week", "gmv"], "rows": "all"}] + + +def build(catalog: dict, *, sources=SOURCES, snapshots=SNAPSHOTS): + def load(artifact): + if artifact not in snapshots: + raise ValueError("取不回来") + return snapshots[artifact] + + return scope.build(catalog, sources=sources, load=load) + + +def test_no_conclusions_no_scope(): + assert scope.build({"m:gmv": {"kind": "metric"}}, sources=SOURCES) is None + + +def test_the_sections_follow_the_verdicts(): + region = fake_result(inputs=data()) + channel = fake_result(verdict="dispersed", inputs=[*data(), {"ref": "A1", "artifact": "a" * 63 + "1", + "role": "parent"}], + params={"by": ["channel"], "label": "销售额"}, hypothesis="华东是不是线上拖累的") + channel["table"]["columns"][0] = "channel" + channel["table"]["labels"] = {"channel": "渠道"} + catalog = { + "A1": entry("A1", region), + "A2": entry("A2", fake_result("baseline", None, "outside_band")), + "A3": entry("A3", channel), + "A4": entry("A4", fake_result("differ", "rate", "no_evidence")), + "A5": entry("A5", fake_result("trend", None, None, status="refused", reason_code="history_short")), + "A6": entry("A6", fake_result("differ", "rate", "differs")), + } + block = build(catalog) + assert [i["alias"] for i in block["phenomena"]] == ["A2"] + assert [(i["alias"], i["parent"], i["dims"], i["verdict"]) for i in block["decomposed"]] == [ + ("A1", None, ["地区"], "driver"), ("A3", "A1", ["渠道"], "dispersed")] + assert [i["alias"] for i in block["excluded"]] == ["A3", "A4"] + assert [(i["alias"], i["reason"]) for i in block["refused"]] == [("A5", "历史只有 5 期,至少要 8 期")] + assert block["tests"] == 2 and block["corrected"] is False + assert block["decomposed"][0]["phrase"] == region["phrase"] + assert "华东是不是线上拖累的" not in str(block), "agent 写的假设不进分析范围" + + +def test_drill_chains_keep_each_parent_ahead_of_its_children(): + def child(of: str) -> dict: + return fake_result(inputs=[*data(), {"ref": of, "artifact": "a" * 63 + of[-1], "role": "parent"}]) + + catalog = {"A1": entry("A1", fake_result(inputs=data())), "A2": entry("A2", fake_result(inputs=data())), + "A3": entry("A3", child("A1")), "A4": entry("A4", child("A3"))} + assert [i["alias"] for i in build(catalog)["decomposed"]] == ["A1", "A3", "A4", "A2"] + + +def test_candidate_dimensions_come_from_the_fact_table_and_its_dimensions(): + block = build({"A1": entry("A1", fake_result(inputs=data()))}) + # 地区拆过了;会员等级没有码值、客户编号是标识、手机号遮罩、金额是流量、周取值太多:都不是候选 + assert block["not_decomposed"] == ["渠道", "订单状态", "门店类型", "城市"] and block["note"] is None + assert block["tests"] == 0 and block["corrected"] is None + + +def test_a_dimension_that_does_not_match_the_catalog_is_reported_not_guessed(): + result = fake_result(inputs=data(), params={"by": ["地区名"], "label": "销售额"}) + result["table"]["columns"][0] = "地区名" + result["table"]["labels"] = {"地区名": "地区名"} + block = build({"A1": entry("A1", result)}) + assert block["not_decomposed"] is None and block["note"] == "候选维度核对不了:拆解按的「地区名」对不上数据目录里的列" + + +@pytest.mark.parametrize("kwargs, note", [ + ({"sources": None}, scope.NOTE_NO_CATALOG), + ({"sources": {"shop": {"tables": {}, "masked": []}}}, scope.NOTE_NO_NOTES), + ({"sources": {}}, scope.NOTE_NO_CATALOG), + ({"snapshots": {}}, scope.NOTE_NO_QUERY), + ({"sources": {"shop": {"tables": {"orders": {"columns": NOTES["orders"]["columns"]}, + "stores": NOTES["stores"]}, "masked": []}}}, scope.NOTE_NO_FACT), +]) +def test_what_cannot_be_checked_is_said_plainly(kwargs, note): + block = build({"A1": entry("A1", fake_result(inputs=data()))}, **kwargs) + assert block["not_decomposed"] is None and block["note"] == note + assert [i["alias"] for i in block["decomposed"]] == ["A1"], "核对不了的只是候选维度,别的照写" + + +def test_a_single_unlabelled_table_counts_as_the_fact_table(): + notes = {"orders": {k: v for k, v in NOTES["orders"].items() if k != "kind"}} + sql = "SELECT region, SUM(amount) AS gmv FROM orders GROUP BY region" + block = build({"A1": entry("A1", fake_result(inputs=data()))}, sources={"shop": {"tables": notes, "masked": []}}, + snapshots={SNAP: {**SNAPSHOTS[SNAP], "sql": sql}}) + assert block["not_decomposed"] == ["渠道", "订单状态", "手机号"] + + +def test_without_a_dimension_decomposition_the_candidates_are_not_checked(): + block = build({"A1": entry("A1", fake_result("baseline", None, "within_band", inputs=data()))}) + assert block["not_decomposed"] is None and block["note"] == scope.NOTE_NO_DECOMPOSE + + +@pytest.fixture +async def shop(tmp_path): + path = tmp_path / "scope_shop.db" + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, region TEXT, channel TEXT, store_id INTEGER, " + "phone TEXT, amount REAL, week TEXT);" + "CREATE TABLE stores (id INTEGER PRIMARY KEY, store_type TEXT, city TEXT);") + db.commit() + db.close() + async with SessionLocal() as session: + row = DataSource(name=f"scope_{uuid.uuid4().hex[:6]}", kind="sqlite", database=str(path), + options={"mask_columns": "phone"}) + session.add(row) + await session.commit() + row.schema_cache = await introspect(row) + await session.commit() + await session.refresh(row) + for table, notes in NOTES.items(): + await data_catalog.write_entry(session, row.id, table, notes, if_version=0, actor=None) + session.expunge(row) + yield row + await drop_source(row.id) + + +async def test_the_report_reads_the_catalog_through_the_run_view(shop): + facts = await scope.source_facts([shop.name, "nope"]) + assert set(facts) == {shop.name} and facts[shop.name]["masked"] == ["phone"] + assert set(facts[shop.name]["tables"]) == {"orders", "stores"} + assert await scope.source_facts([shop.name], CatalogView(mode="off")) is None + + snapshot = {**SNAPSHOTS[SNAP], "source": shop.name} + catalog = {"Q1": {"alias": "Q1", "kind": "query", "artifact": SNAP, "source": shop.name}, + "A1": entry("A1", fake_result(inputs=data()))} + block = await scope.scope_of(catalog, None, load=lambda a: snapshot) + assert block["not_decomposed"] == ["渠道", "订单状态", "门店类型", "城市"] + block = await scope.scope_of(catalog, {"mode": "off"}, load=lambda a: snapshot) + assert block["not_decomposed"] is None and block["note"] == scope.NOTE_NO_CATALOG diff --git a/backend/tests/test_approval_default.py b/backend/tests/test_approval_default.py index 705718d7..48193cdd 100644 --- a/backend/tests/test_approval_default.py +++ b/backend/tests/test_approval_default.py @@ -159,7 +159,8 @@ def _governable(tool: str): metrics=[{"id": "done", "name": "已执行", "unit": "次", "expression": "1"}]), # 受管契约要核对报告撰写节点的文档(门禁 G1),叙述模式发不成受管 node("write", "report", instructions="写执行结果", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", + analysis_claims="strict"), node("out", "output", fields=[{"name": "结果", "value": "{{ nodes.q }}"}], contract={"metrics_from": ["caliber"], "report_from": "write", "required": ["done"], "strict": True}), ) diff --git a/backend/tests/test_autofix_assist.py b/backend/tests/test_autofix_assist.py index 96015bb5..bf6e01cf 100644 --- a/backend/tests/test_autofix_assist.py +++ b/backend/tests/test_autofix_assist.py @@ -40,7 +40,7 @@ def two_exits() -> dict: node("card", "metrics", "周报口径卡", caliber="周报口径", metrics=[ {"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}]), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]), node("raw", "output", "原始数", fields=[{"name": "数", "value": "{{ nodes.fetch }}"}]), ] @@ -230,7 +230,7 @@ def guarded() -> dict: node("team", "supervisor", "复核团队", goal="复核", agents=[{"name": "checker", "tools": []}]), node("gate", "human", "人工把关", prompt="确认数字"), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract=CONTRACT), ] edges = [{"id": f"e{i}", "source": a, "target": b} for i, (a, b) in enumerate( diff --git a/backend/tests/test_autofix_governance.py b/backend/tests/test_autofix_governance.py index 83f4c0f7..f2f60360 100644 --- a/backend/tests/test_autofix_governance.py +++ b/backend/tests/test_autofix_governance.py @@ -18,7 +18,7 @@ from app.engine.governance import publish_issues from app.engine.schema import GraphSpec from app.main import app -STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation"} +STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation", "analysis_claims": "strict"} SCHEMA = {"type": "object", "properties": {"gmv": {"type": "number"}}} @@ -88,20 +88,21 @@ def test_report_policy_is_filled_in_with_one_auto_fix(): fix = plan(graph)[fid] assert fix["kind"] == "auto" and fix["node_id"] == "write" assert fix["preview"]["after"] == STRICT and fix["preview"]["before"] == { - "numbers": "off", "on_violation": None, "claims": None} + "numbers": "off", "on_violation": None, "claims": None, "analysis_claims": None} out = apply_fixes(graph, [fid], level="governed") assert out["applied"] == [fid] and out["rejected"] == [] and out["ok"] is True assert {k: config(out["graph"], "write")[k] for k in STRICT} == STRICT assert config(out["graph"], "write")["instructions"] == "写周报" # 别的配置原样留着 assert [(c["field"], c["before"], c["after"]) for c in out["changes"]] == [ - ("numbers", "off", "strict"), ("on_violation", None, "fail"), ("claims", None, "require_citation")] + ("numbers", "off", "strict"), ("on_violation", None, "fail"), ("claims", None, "require_citation"), + ("analysis_claims", None, "strict")] assert out["ops"] == [{"op": "update_node", "id": "write", "config": STRICT}] # 坐标、视口这些前端的东西原样留着 assert find(out["graph"], "write")["position"] == {"x": 10, "y": 20} and out["graph"]["viewport"]["zoom"] == 1 def test_only_the_missing_settings_are_written(): - graph = traceable(report={"numbers": "strict", "claims": "require_citation"}) + graph = traceable(report={"numbers": "strict", "claims": "require_citation", "analysis_claims": "strict"}) fix = plan(graph)["governed.report_policy:write"] assert fix["preview"] == {"field": "on_violation", "before": None, "after": "fail"} out = apply_fixes(graph, [fix["id"]], level="governed") diff --git a/backend/tests/test_autofix_graph_defaults.py b/backend/tests/test_autofix_graph_defaults.py index d9265c2c..979a95d1 100644 --- a/backend/tests/test_autofix_graph_defaults.py +++ b/backend/tests/test_autofix_graph_defaults.py @@ -40,7 +40,7 @@ def weekly(default: str | None = "never", **ask_config) -> dict: node("card", "metrics", "周报口径卡", caliber="周报口径", metrics=[ {"id": "gmv", "name": "销售额", "unit": "元", "expression": "vars.gmv"}]), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={"report_from": "write", "metrics_from": ["card"], "required": ["gmv"], "strict": True}), ] diff --git a/backend/tests/test_autofix_rules.py b/backend/tests/test_autofix_rules.py index 581a28c1..0835f14a 100644 --- a/backend/tests/test_autofix_rules.py +++ b/backend/tests/test_autofix_rules.py @@ -33,7 +33,7 @@ def weekly(**contract_overrides) -> dict: {"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}, {"id": "orders", "name": "订单数", "unit": "单", "expression": "cell(nodes.fetch, 0, 'orders')"}]), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={k: v for k, v in contract.items() if v is not None}), ] @@ -72,7 +72,8 @@ def add_card(graph: dict, nid: str = "card2") -> dict: def add_report(graph: dict, nid: str = "write2") -> dict: graph["nodes"].insert(4, node(nid, "report", "第二份报告", instructions="写月报", - numbers="strict", on_violation="fail", claims="require_citation")) + numbers="strict", on_violation="fail", claims="require_citation", + analysis_claims="strict")) graph["edges"] += [{"source": "card", "target": nid}, {"source": nid, "target": "done"}] return graph diff --git a/backend/tests/test_contract_analysis_claims.py b/backend/tests/test_contract_analysis_claims.py new file mode 100644 index 00000000..d61f6b47 --- /dev/null +++ b/backend/tests/test_contract_analysis_claims.py @@ -0,0 +1,372 @@ +"""出口契约(引用模式)的分析说法复核、口径卡指标的可比性、报告引用的指标的血缘(00-总方案 §3.4、§3.5、§3.9,D9、D15)。 + +- 分析说法:出口按报告文档记下的那一项独立再核一遍(verify_doc)。strict 有违规记一条缺口(降档),报告节点报上来的同一条 + 不重复收;check 只写进出具声明(analysis_claims,counted 为 false),不影响档位;没记这一项的老文档不核 +- 可比性:报告引用了的、契约必需的指标两期不可比记缺口(降档),有条件可比的只写进出具声明(comparability) +- 血缘:报告引用的指标([[m:]] 片段、句末 [[see:m:…]])输入追不到原始数据的,受管级别的正式运行记缺口,其余写进出具声明的 + untraced(counted 为 false) +""" +from __future__ import annotations + +import asyncio +import sqlite3 +import uuid + +import pytest +from httpx import ASGITransport, AsyncClient +from langchain_core.messages import AIMessage +from sqlalchemy import select + +from app.data.engine import engines +from app.db.base import SessionLocal +from app.db.models import DataSource, Run, RunEvent, Workflow, WorkflowVersion +from app.engine import analysis_claims as ac +from app.engine import compiler +from app.engine.nodes.io import _analysis_claims, _comparability +from app.engine.runner import run_manager +from app.engine.schema import NodeType +from app.main import app + +METRICS = [{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 1, "expression": "vars.kpi.gmv"}, + {"id": "wow", "name": "环比增幅", "unit": "%", "decimals": 1, "format": "plain", "expression": "vars.kpi.wow"}] +SOURCE = "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv]]" +PLAIN = "本周销售额 [[m:gmv]]。[[see:m:gmv]]" + + +@pytest.fixture(autouse=True) +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +def node(nid, ntype, **config): + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}} + + +def weekly(*, report=None, contract=None, fetch=None, metrics=METRICS) -> dict: + """取数 → 口径卡 → 报告撰写 → 出口(引用模式契约)。缺省取数是数据整形(追不到原始数据)。""" + nodes = [ + node("start", "input", fields=[{"name": "week", "default": "2026-W37"}]), + fetch or node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5, 'wow': -3.1}", + assign_to="kpi"), + node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=metrics), + node("write", "report", instructions="写周报", **(report or {})), + node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], + contract={"report_from": "write", "metrics_from": ["caliber"], "required": ["gmv"], "strict": True, + **(contract or {})}), + ] + ids = [n["id"] for n in nodes] + return {"nodes": nodes, "edges": [{"source": a, "target": b} for a, b in zip(ids, ids[1:])]} + + +def writes(monkeypatch, text: str) -> None: + from app.providers import mock_model + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", lambda self, messages: AIMessage(content=text)) + + +async def wait(run_id: str) -> Run: + for _ in range(400): + await asyncio.sleep(0.05) + async with SessionLocal() as session: + row = await session.get(Run, run_id) + if row.status in ("succeeded", "failed") and row.manifest_seq is not None: + return row + raise AssertionError(f"run {run_id} 没跑完:{row.status}") + + +async def issued(graph, *, run_class="exploratory") -> dict: + run = await run_manager.start(graph=graph, input_payload={}, run_class=run_class) + row = await wait(run.id) + assert row.status == "succeeded", row.error + return row.output["_issuance"] + + +async def governed(client, graph) -> dict: + """把这张图发布成受管级别,从发布版本发起正式运行。""" + async with SessionLocal() as session: + wf = Workflow(name=f"分析-{uuid.uuid4().hex[:6]}", graph=graph, status="governed", published_version=1) + session.add(wf) + await session.flush() + session.add(WorkflowVersion(workflow_id=wf.id, version=1, graph=graph)) + await session.commit() + wf_id = wf.id + res = await client.post("/api/runs", json={"workflow_id": wf_id, "run_class": "formal"}) + assert res.status_code == 201, res.text + row = await wait(res.json()["id"]) + assert row.status == "succeeded", row.error + return row.output["_issuance"] + + +async def issuance_event(run_id: str) -> dict: + async with SessionLocal() as session: + [event] = (await session.execute(select(RunEvent).where( + RunEvent.run_id == run_id, RunEvent.type == "issuance"))).scalars() + return event.data + + +def said_gaps(issuance: dict) -> list[str]: + return [g for g in issuance["gaps"] if "分析说法" in g] + + +# -------------------------------------------------------------------------- +# 分析说法:出口独立复核 +# -------------------------------------------------------------------------- + + +async def test_strict_leftovers_degrade_with_one_gap_from_the_exit(monkeypatch): + writes(monkeypatch, SOURCE) + issuance = await issued(weekly(report={"analysis_claims": "strict"})) + assert issuance["tier"] == "degraded" + [gap] = said_gaps(issuance) + assert gap.startswith("报告「write」有 1 处分析说法未通过核对(1 处判断没挂分析结论)"), "报告节点那一条不重复收" + declared = issuance["analysis_claims"] + assert declared["mode"] == "strict" and declared["counted"] is True and declared["count"] == 1 + [v] = declared["violations"] + assert v["code"] == ac.UNCITED and v["text"] == "主要来自" and v["claim"] == "source" and v["span"] + + +async def test_check_leftovers_are_declared_but_do_not_change_the_tier(monkeypatch): + writes(monkeypatch, SOURCE) + issuance = await issued(weekly()) + assert issuance["tier"] == "formal" and said_gaps(issuance) == [] + declared = issuance["analysis_claims"] + assert declared["mode"] == "check" and declared["counted"] is False and declared["counts"] == {ac.UNCITED: 1} + + +async def test_a_clean_report_declares_nothing_under_check_and_a_clean_slate_under_strict(monkeypatch): + writes(monkeypatch, PLAIN) + assert "analysis_claims" not in await issued(weekly()) + issuance = await issued(weekly(report={"analysis_claims": "strict"})) + assert issuance["tier"] == "formal" and issuance["analysis_claims"] == { + "mode": "strict", "count": 0, "counts": {}, "counted": True, "violations": []} + + +async def test_off_and_old_documents_are_not_checked(monkeypatch): + writes(monkeypatch, SOURCE) + issuance = await issued(weekly(report={"analysis_claims": "off"})) + assert "analysis_claims" not in issuance and said_gaps(issuance) == [] and issuance["tier"] == "formal" + + +async def test_a_narrative_contract_still_takes_the_report_gap(monkeypatch): + writes(monkeypatch, SOURCE) + graph = weekly(report={"analysis_claims": "strict"}) + contract = graph["nodes"][-1]["data"]["config"]["contract"] + del contract["report_from"] + contract["narrative"] = "{{ nodes.write.text }}" + issuance = await issued(graph) + [gap] = said_gaps(issuance) + assert gap.startswith("报告撰写「write」:报告有 1 处分析说法未通过核对") and issuance["tier"] == "degraded" + + +def test_the_exit_policy_takes_the_stricter_of_the_doc_and_the_node(): + def run(doc, payload, found=()): + out = {"gaps": [], "analysis": None, "analysis_skip": {}} + _analysis_claims(out, doc, payload, list(found), title="周报", node_id="write") + return out + + violation = {"code": ac.UNCITED, "text": "主要来自", "claim": "source", "op": "decompose", "message": "…"} + # 老文档(没有这一项)、节点也没写:不核 + assert run({}, {"claims": "off"}) == {"gaps": [], "analysis": None, "analysis_skip": {}} + # 节点要求 strict,文档里却没有核对记录:照实记缺口 + assert run({}, {"analysis_claims": "strict"})["gaps"] == [ + "报告「周报」要求严格核对分析说法,但文档中没有分析说法的核对记录,分析说法未核对"] + assert run({}, {"analysis_claims": "check"})["gaps"] == [] + # 文档记的是 check、节点写的是 strict:按更严的 + out = run({ac.DOC_FIELD: ac.record("check")}, {"analysis_claims": "strict", "analysis_gap": "报告有 1 处…"}, + [violation]) + assert len(out["gaps"]) == 1 and out["analysis"]["counted"] is True + assert out["analysis_skip"] == {"write": {"报告有 1 处…"}} + + +# -------------------------------------------------------------------------- +# 可比性 +# -------------------------------------------------------------------------- + + +def test_comparability_gaps_only_for_incomparable_metrics(): + metrics = [ + {"id": "wow", "name": "环比增幅", "comparability": {"verdict": "incomparable", "phrase": "两期不可比:本期只有 3 天数据", + "reasons": ["本期只有 3 天数据"], "artifact": "c" * 64}}, + {"id": "aov", "name": "客单价", "comparability": {"verdict": "conditional", + "phrase": "两期有条件可比:两段的周末天数不同:4 天对 6 天"}}, + {"id": "gmv", "name": "销售额", "comparability": {"verdict": "comparable", "phrase": "两期可比"}}, + {"id": "orders", "name": "订单数"}, + ] + gaps, declared = _comparability(metrics + metrics[:1]) + assert gaps == ["指标「环比增幅」两期不可比:本期只有 3 天数据"] + assert [(d["metric"], d["verdict"]) for d in declared] == [("wow", "incomparable"), ("aov", "conditional")] + assert declared[0]["reasons"] == ["本期只有 3 天数据"] and declared[0]["artifact"] == "c" * 64 + + +@pytest.fixture +def comparability(monkeypatch): + """口径卡给指标记上可比性(口径卡跨两份同形查询算环比时自动做的检查由入口包实现;这里直接记上)。""" + marks: dict[str, dict] = {} + original = compiler.RUNNERS[NodeType.METRICS] + + async def card(state, ctx): + updates = await original(state, ctx) + for metric in updates["nodes"][ctx.node.id]["metrics"]: + if metric["id"] in marks: + metric["comparability"] = marks[metric["id"]] + return updates + + monkeypatch.setitem(compiler.RUNNERS, NodeType.METRICS, card) + return marks + + +async def test_a_cited_incomparable_metric_degrades_and_a_conditional_one_is_noted(monkeypatch, comparability): + comparability["wow"] = {"verdict": "incomparable", "phrase": "两期不可比:本期只有 3 天数据", + "reasons": ["本期只有 3 天数据"]} + writes(monkeypatch, "本周销售额 [[m:gmv]],环比 [[m:wow]]。[[see:m:gmv,m:wow]]") + issuance = await issued(weekly()) + assert issuance["tier"] == "degraded" and "指标「环比增幅」两期不可比:本期只有 3 天数据" in issuance["gaps"] + assert [c["metric"] for c in issuance["comparability"]] == ["wow"] + comparability["wow"] = {"verdict": "conditional", "phrase": "两期有条件可比:两段的周末天数不同"} + issuance = await issued(weekly()) + assert issuance["tier"] == "formal" and issuance["comparability"][0]["verdict"] == "conditional" + + +async def test_an_incomparable_metric_nobody_cites_or_requires_is_left_alone(monkeypatch, comparability): + comparability["wow"] = {"verdict": "incomparable", "phrase": "两期不可比:本期只有 3 天数据"} + writes(monkeypatch, PLAIN) + issuance = await issued(weekly()) + assert issuance["tier"] == "formal" and "comparability" not in issuance + # 契约必需的指标不引用也算 + issuance = await issued(weekly(contract={"required": ["gmv", "wow"]})) + assert "指标「环比增幅」两期不可比:本期只有 3 天数据" in issuance["gaps"] + + +# -------------------------------------------------------------------------- +# 血缘:报告引用的指标追没追到原始数据 +# -------------------------------------------------------------------------- + + +async def test_a_cited_metric_that_stops_at_a_transform_is_only_noted_outside_governed_runs(monkeypatch): + writes(monkeypatch, PLAIN) + issuance = await issued(weekly(), run_class="formal") + assert issuance["tier"] == "formal" and not any("没追到原始数据" in g for g in issuance["gaps"]) + untraced = issuance["untraced"] + assert untraced["counted"] is False and [m["metric"] for m in untraced["metrics"]] == ["gmv"] + assert untraced["metrics"][0]["stops"][0]["node_id"] == "fetch" + + +async def test_a_governed_formal_run_counts_the_untraced_cited_metric(client, monkeypatch): + writes(monkeypatch, PLAIN) + issuance = await governed(client, weekly()) + assert issuance["tier"] == "degraded" + [gap] = [g for g in issuance["gaps"] if "没追到原始数据" in g] + assert gap.startswith("指标「销售额」的输入没追到原始数据:vars.kpi.gmv(停在「fetch」)") + assert issuance["untraced"]["counted"] is True + # 没被引用的指标(环比增幅同样停在整形节点)不算:只看报告引用了的 + assert not any("环比增幅" in g for g in issuance["gaps"]) + + +@pytest.fixture +async def shop(tmp_path): + path = tmp_path / "shop.db" + db = sqlite3.connect(path) + db.executescript("CREATE TABLE orders (id INTEGER PRIMARY KEY, week TEXT, amount REAL);") + db.executemany("INSERT INTO orders VALUES (?, ?, ?)", [(1, "2026-W37", 100.5), (2, "2026-W37", 200.0)]) + db.commit() + db.close() + async with SessionLocal() as session: + row = (await session.execute(select(DataSource).where(DataSource.name == "shop"))).scalar_one_or_none() + if row is None: + row = DataSource(name="shop", kind="sqlite", database=str(path), readonly=True, enabled=True) + session.add(row) + else: + row.database, row.kind, row.enabled, row.readonly, row.options = str(path), "sqlite", True, True, {} + await session.commit() + source_id = row.id + await engines.invalidate(source_id) + yield + await engines.invalidate(source_id) + + +async def test_a_metric_read_from_a_query_cell_is_traced(client, monkeypatch, shop): + writes(monkeypatch, PLAIN) + fetch = node("fetch", "tool", tool="db_query__shop", args={"sql": "SELECT SUM(amount) AS gmv FROM orders"}) + graph = weekly(fetch=fetch, metrics=[{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 1, + "expression": "cell(nodes.fetch, 0, 'gmv')"}]) + issuance = await governed(client, graph) + assert "untraced" not in issuance and not any("没追到原始数据" in g for g in issuance["gaps"]) + + +# -------------------------------------------------------------------------- +# 引用了分析结论:输入查询的 SQL 检查问题计入缺口,具名标量记进逐个数字的出处 +# -------------------------------------------------------------------------- + + +@pytest.fixture +def analyses(monkeypatch): + """写作目录里多几条分析结论:{A 编号: 结论工件 id}。台账里的分析结论由入口(分析卡、Agent 的分析工具)记,这里直接 + 补进目录:报告节点和出口复核按同一个 report_catalog 建目录,一处补上。""" + from app.core import artifact_store + from app.engine.evidence import make_eid + from app.engine.nodes import report as report_mod + + added: dict[str, str] = {} + original = report_mod.report_catalog + + def catalog(state, spec, node): + out = original(state, spec, node) + for alias, artifact in added.items(): + out[alias] = {"alias": alias, "kind": "analysis", "artifact": artifact, "item": "drop", + "eid": make_eid("analysis", artifact, {}), "locator": {}, + "result": artifact_store.load(artifact)} + return out + + monkeypatch.setattr(report_mod, "report_catalog", catalog) + return added + + +async def stored_driver(*, checks=None) -> str: + """一份「销售额下降主要来自华东」的拆解结论,输入是一份(可能带着 SQL 检查问题的)查询快照,都存进工件库。""" + from app.analysis.testing import fake_result + from app.core import artifact_store + + query = await artifact_store.put_json({"source": "shop", "sql": "SELECT region, week, SUM(amount) AS gmv FROM orders", + "columns": ["region", "week", "gmv"], "rows": [["华东", "W41", 820]], + "truncated": False, **({"checks": checks} if checks else {})}, + kind="query_snapshot") + result = fake_result(inputs=[{"ref": "Q2", "artifact": query, "role": "data", + "columns": ["region", "week", "gmv"], "rows": "all"}]) + return await artifact_store.put_json(result, kind="analysis_result") + + +FANOUT = {"code": "fanout_sum", "level": "error", "message": "一对多关联后求和,订单金额被重复计算。改法:先汇总再关联"} + + +@pytest.mark.parametrize("text", [ + "[[a:A1]]。[[see:m:gmv]]", + "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv,A1]]", + "华东占变化的 [[a:A1.top_share|pct]]。[[see:m:gmv]]", +]) +async def test_an_analysis_built_on_a_failing_query_degrades_like_the_query_itself(monkeypatch, analyses, text): + analyses["A1"] = await stored_driver(checks=[FANOUT]) + writes(monkeypatch, text) + issuance = await issued(weekly()) + assert issuance["tier"] == "degraded" + [gap] = [g for g in issuance["gaps"] if "SQL 检查" in g] + assert "一对多关联后求和" in gap and "A1" in gap + analyses["A1"] = await stored_driver() + clean = await issued(weekly()) + assert clean["tier"] == "formal" and not any("SQL 检查" in g for g in clean["gaps"]) + + +async def test_a_named_scalar_is_listed_as_an_analysis_number(monkeypatch, analyses): + analyses["A1"] = await stored_driver() + writes(monkeypatch, "华东占变化的 [[a:A1.top_share|pct]],下降主要来自华东。[[see:m:gmv,A1]]") + issuance = await issued(weekly()) + [hit] = [m for m in issuance["matched"] if m.get("analysis")] + assert hit["analysis"] == "A1.top_share" and hit["token"] == "61.9%" and "input" not in hit + assert "analysis_claims" not in issuance, "判断词挂对了:check 下没有可标注的" diff --git a/backend/tests/test_contract_cells.py b/backend/tests/test_contract_cells.py index 6f22f06b..977f3131 100644 --- a/backend/tests/test_contract_cells.py +++ b/backend/tests/test_contract_cells.py @@ -344,7 +344,7 @@ def cells_only(**contract): node("fetch", "tool", tool="db_query__shop", args={"sql": "SELECT SUM(amount) AS gmv, COUNT(*) AS orders FROM orders"}), node("write", "report", instructions="写周报", numbers="strict", on_violation="fail", - claims="require_citation"), + claims="require_citation", analysis_claims="strict"), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract=contract), ] return {"nodes": nodes, "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]} diff --git a/backend/tests/test_copilot_prompt_evidence.py b/backend/tests/test_copilot_prompt_evidence.py index ee6f9beb..b2659630 100644 --- a/backend/tests/test_copilot_prompt_evidence.py +++ b/backend/tests/test_copilot_prompt_evidence.py @@ -202,7 +202,7 @@ def ask_report_graph() -> dict: g("start", "input", "问题"), g("ask", "agent", "查数", tools=["db_query__shop"], prompt="查活跃用户数和用户总数", approval="dangerous"), g("report", "report", "写答案", instructions="回答:{{ input.question }}", numbers="strict", - on_violation="fail", claims="require_citation"), + on_violation="fail", claims="require_citation", analysis_claims="strict"), g("out", "output", "输出答案", fields=[{"name": "answer", "value": "{{ nodes.report.text }}"}]), ], "edges": [{"id": f"e{i}", "source": a, "target": b} diff --git a/backend/tests/test_evidence_audit.py b/backend/tests/test_evidence_audit.py index 02aee673..4b560297 100644 --- a/backend/tests/test_evidence_audit.py +++ b/backend/tests/test_evidence_audit.py @@ -122,7 +122,8 @@ async def events(run_id: str, etype: str, node_id: str | None = None) -> list[Ru async def report_run(monkeypatch, text=WRITE) -> tuple[Run, dict]: script(monkeypatch, text) row = await finish(chain(node("start", "input"), node("fetch", "tool", tool=TOOL, args={"sql": SQL}), - node("write", "report", instructions="写一句", max_repairs=0), + # 「增长主要来自新客」没有分析结论可挂:分析说法核对关掉,审计表只看原有的几类 + node("write", "report", instructions="写一句", max_repairs=0, analysis_claims="off"), node("out", "output", fields=[{"name": "r", "value": "{{ nodes.write.text }}"}]))) assert row.status == "succeeded", row.error [checked] = await events(row.id, "report.checked", "write") diff --git a/backend/tests/test_governance_analysis_claims.py b/backend/tests/test_governance_analysis_claims.py new file mode 100644 index 00000000..9d481dfb --- /dev/null +++ b/backend/tests/test_governance_analysis_claims.py @@ -0,0 +1,182 @@ +"""门禁 G3 加的一条:受管级别的报告撰写节点要把分析说法核对设成严格(00-总方案 §3.5,D8)。 + +- 没写(运行时是重写一次后标出)、写了 check 或 off:受管级别挡住发布(error),已发布级别只警告;写错的值交给校验 +- 自动修复一键写明;一键升级成受管、按口径出具起草的报告节点照同一份要求写(REPORT_POLICY) +- 已经发布的受管版本照常发起正式运行(报告节点按缺省的 check 核、只标注),下次发布才按新规则查 +- 白话里说到分析说法 +""" +from __future__ import annotations + +import asyncio +import copy + +import pytest +from httpx import ASGITransport, AsyncClient +from langchain_core.messages import AIMessage + +from app.db.base import SessionLocal +from app.db.models import Run, Workflow, WorkflowVersion +from app.engine.autofix import apply_fixes, plan_fixes +from app.engine.governance import REPORT_POLICY, lint_for_publish, publish_issues +from app.engine.labels import field_label, option_label +from app.engine.runner import run_manager +from app.engine.schema import GraphSpec, validate_graph +from app.main import app +from app.plain import plain_of + +STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation", "analysis_claims": "strict"} + + +def node(nid, ntype, label=None, **config): + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": label or nid, "config": config}} + + +def traceable(report: dict) -> dict: + """input → 查库 → 口径卡 → 报告撰写 → 出具(引用模式契约):别的受管要求都满足。""" + nodes = [ + node("start", "input", "周期", fields=[{"name": "week", "default": "2026-W37"}]), + node("fetch", "tool", "取数", tool="db_query__shop", args={"sql": "SELECT SUM(amount) AS gmv FROM orders"}), + node("card", "metrics", "周报口径卡", caliber="周报口径", metrics=[ + {"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}]), + node("write", "report", "报告撰写", instructions="写周报", **report), + node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], + contract={"report_from": "write", "metrics_from": ["card"], "required": ["gmv"], "strict": True}), + ] + return {"nodes": nodes, "edges": [{"source": a["id"], "target": b["id"]} for a, b in zip(nodes, nodes[1:])]} + + +def policy_issues(graph: dict, level: str = "governed") -> list: + return [i for i in lint_for_publish(GraphSpec.model_validate(graph), level=level).issues + if i.code == "governed.report_policy"] + + +def test_the_rule_is_part_of_the_report_policy(): + assert ("analysis_claims", "strict") in [(k, v) for k, v, _ in REPORT_POLICY] + + +@pytest.mark.parametrize("value, now", [(None, "当前未设置"), ("check", "当前为「重写一次后标出」"), + ("off", "当前为「不核对」")]) +def test_a_governed_report_must_check_analysis_claims_strictly(value, now): + report = {k: v for k, v in STRICT.items() if k != "analysis_claims"} + if value is not None: + report["analysis_claims"] = value + [issue] = policy_issues(traceable(report)) + assert issue.level == "error" and issue.node_id == "write" and issue.field == "analysis_claims" + assert f"「{field_label('analysis_claims')}」设为「{option_label('analysis_claims', 'strict')}」({now})" \ + in issue.message + assert "「未引用的数字」" not in issue.message, "别的几项都写明了,不再点名" + assert [i.level for i in policy_issues(traceable(report), "published")] == ["warning"] + + +def test_strict_passes_and_graph_defaults_count(): + assert policy_issues(traceable(STRICT)) == [] + graph = traceable({k: v for k, v in STRICT.items() if k != "analysis_claims"}) + graph["defaults"] = {"analysis_claims": "strict"} + assert policy_issues(graph) == [] + + +def test_a_bad_value_is_left_to_validation(): + graph = traceable({**STRICT, "analysis_claims": "loose"}) + assert policy_issues(graph) == [] + [bad] = [i for i in validate_graph(GraphSpec.model_validate(graph)).issues + if i.code == "report.analysis_claims_invalid"] + assert bad.level == "error" and bad.field == "analysis_claims" + + +def test_the_autofix_writes_it_in(): + graph = traceable({k: v for k, v in STRICT.items() if k != "analysis_claims"}) + spec = GraphSpec.model_validate(graph) + fixes = {f["id"]: f for f in plan_fixes(spec, publish_issues(spec, level="governed"), level="governed")} + fix = fixes["governed.report_policy:write"] + assert fix["kind"] == "auto" and fix["preview"] == {"field": "analysis_claims", "before": None, "after": "strict"} + out = apply_fixes(graph, [fix["id"]], level="governed") + assert out["ok"] is True + write = next(n for n in out["graph"]["nodes"] if n["id"] == "write") + assert write["data"]["config"]["analysis_claims"] == "strict" + + +def test_a_governed_upgrade_writes_the_strict_setting(): + from app.engine.upgrade import _policy + + assert _policy("governed", {"numbers": "strict"}, {})["analysis_claims"] == "strict" + assert _policy("governed", {"analysis_claims": "strict"}, {}).get("analysis_claims") is None + assert _policy("published", {}, {}) == {} + + +def test_the_plain_wording_mentions_analysis_claims(): + plain = plain_of("governed.report_policy") + assert "分析结论" in plain.why and "分析说法核对" in plain.action + + +def test_template_nine_stays_publishable_as_governed(): + from app.seed import TEMPLATES + + tpl = next(t for t in TEMPLATES if t["name"].startswith("⑨")) + graph = copy.deepcopy({"nodes": tpl["nodes"], "edges": tpl["edges"]}) + assert next(n for n in graph["nodes"] if n["type"] == "report")["data"]["config"]["analysis_claims"] == "strict" + assert policy_issues(graph) == [] + + +@pytest.fixture +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +@pytest.fixture +async def client(): + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c: + yield c + + +async def test_an_already_governed_version_without_the_setting_keeps_running(client, engine_up, monkeypatch): + """升级前按受管发布的版本(报告节点没写分析说法核对)照常发起正式运行,按缺省的 check 核;再发布时才按新规则查。""" + from app.providers import mock_model + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", + lambda self, messages: AIMessage(content="本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv]]")) + graph = traceable({k: v for k, v in STRICT.items() if k != "analysis_claims"}) + graph["nodes"][1] = node("fetch", "transform", "取数", mode="expression", expression="{'gmv': 300.5}", + assign_to="kpi") + graph["nodes"][2]["data"]["config"]["metrics"] = [ + {"id": "gmv", "name": "销售额", "unit": "元", "expression": "vars.kpi.gmv"}] + async with SessionLocal() as session: + wf = Workflow(name="分析说法-老受管版本", graph=graph, status="governed", published_version=1) + session.add(wf) + await session.flush() + session.add(WorkflowVersion(workflow_id=wf.id, version=1, graph=graph, level="governed")) + await session.commit() + wf_id = wf.id + r = await client.post("/api/runs", json={"workflow_id": wf_id, "run_class": "formal"}) + assert r.status_code == 201, r.text + for _ in range(400): + await asyncio.sleep(0.05) + async with SessionLocal() as session: + row = await session.get(Run, r.json()["id"]) + if row.status in ("succeeded", "failed") and row.manifest_seq is not None: + break + assert row.status == "succeeded", row.error + declared = row.output["_issuance"]["analysis_claims"] + assert declared["mode"] == "check" and declared["counted"] is False + check = (await client.post(f"/api/workflows/{wf_id}/publish-check", json={"level": "governed"})).json() + assert check["ok"] is False + assert any(i["code"] == "governed.report_policy" and i["field"] == "analysis_claims" + for i in check["issues"] if i["level"] == "error") + + +@pytest.mark.parametrize("after", ["check", "off", None]) +def test_loosening_analysis_claims_from_strict_is_refused(after): + from app.engine.autofix import forbidden_changes + + old = traceable(STRICT) + new = copy.deepcopy(old) + write = next(n for n in new["nodes"] if n["id"] == "write")["data"]["config"] + if after is None: + write.pop("analysis_claims") + else: + write["analysis_claims"] = after + [reason] = forbidden_changes(old, new) + assert "「报告撰写」" in reason and "「分析说法核对」" in reason and "「重写后仍有的计入缺口」" in reason + # 往严里改不算 + assert forbidden_changes(new, old) == [] diff --git a/backend/tests/test_governance_judge.py b/backend/tests/test_governance_judge.py index 6462cdaf..51c2f082 100644 --- a/backend/tests/test_governance_judge.py +++ b/backend/tests/test_governance_judge.py @@ -19,7 +19,7 @@ from app.engine.governance import lint_for_publish, publish_issues from app.engine.judge import JUDGE_DEFAULTS from app.engine.schema import GraphSpec, validate_graph -STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation"} +STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation", "analysis_claims": "strict"} JUDGED = {**STRICT, "claims": "judge", "judge": {"max_cost_usd": 0.05}} BUDGET = "governed.judge_budget" @@ -98,7 +98,7 @@ def test_the_budget_follows_the_same_config_rule_as_run_time(): defaults={"judge": {"max_cost_usd": 0.02}}) assert [i.field for i in by_code(graph, BUDGET)] == ["judge.max_cost_usd"] # claims 本身也可以来自图级 defaults - graph = traceable(report={"numbers": "strict", "on_violation": "fail"}, + graph = traceable(report={"numbers": "strict", "on_violation": "fail", "analysis_claims": "strict"}, defaults={"claims": "judge", "judge": {"max_cost_usd": None}}) assert by_code(graph, BUDGET) == [] and by_code(graph, "governed.report_policy") == [] diff --git a/backend/tests/test_governance_report_lint.py b/backend/tests/test_governance_report_lint.py index 5205b542..1ba2fc69 100644 --- a/backend/tests/test_governance_report_lint.py +++ b/backend/tests/test_governance_report_lint.py @@ -25,7 +25,7 @@ from app.main import app from app.seed import TEMPLATES #: 报告撰写节点在受管模板里要写明的三项 -STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation"} +STRICT = {"numbers": "strict", "on_violation": "fail", "claims": "require_citation", "analysis_claims": "strict"} G_CODES = { "governed.report_from_required", "governed.exit_text_source", "governed.text_bypass", @@ -277,7 +277,7 @@ def test_a_looser_setting_is_named(key, value): def test_graph_defaults_count_like_they_do_at_run_time(): graph = traceable(report={"claims": "require_citation"}) - graph["defaults"] = {"numbers": "strict", "on_violation": "fail"} + graph["defaults"] = {"numbers": "strict", "on_violation": "fail", "analysis_claims": "strict"} assert by_code(graph, "governed.report_policy") == [] graph["defaults"]["on_violation"] = "flag" assert [i.field for i in by_code(graph, "governed.report_policy")] == ["on_violation"] diff --git a/backend/tests/test_judge_rework_grading.py b/backend/tests/test_judge_rework_grading.py index 2792765f..75814b50 100644 --- a/backend/tests/test_judge_rework_grading.py +++ b/backend/tests/test_judge_rework_grading.py @@ -149,8 +149,9 @@ def weekly(*, report=None, contract=None) -> dict: node("start", "input", fields=[{"name": "week", "default": "2026-W37"}]), node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5}", assign_to="kpi"), node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=METRICS), + # 这里测的是裁判:写作者那句「增长主要来自新客首单」没有分析结论可挂,分析说法核对关掉,免得多重写一次 node("write", "report", instructions="写周报", **{"claims": "judge", "judge": {"max_cost_usd": 0.05}, - **(report or {})}), + "analysis_claims": "off", **(report or {})}), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={"report_from": "write", "metrics_from": ["caliber"], "required": ["gmv"], "strict": True, **(contract or {})}), diff --git a/backend/tests/test_merge_node.py b/backend/tests/test_merge_node.py index 7d472543..a2fde5d5 100644 --- a/backend/tests/test_merge_node.py +++ b/backend/tests/test_merge_node.py @@ -267,7 +267,8 @@ def test_publish_checks_treat_the_merge_as_traceable_evidence(): graph = store_graph() for n in graph["nodes"]: if n["id"] == "write": - n["data"]["config"].update(numbers="strict", on_violation="fail", claims="require_citation") + n["data"]["config"].update(numbers="strict", on_violation="fail", claims="require_citation", + analysis_claims="strict") if n["id"] == "out": n["data"]["config"]["contract"] = {"report_from": "write", "metrics_from": ["card"], "required": ["conversion"], "strict": True} diff --git a/backend/tests/test_provider_ref_runtime.py b/backend/tests/test_provider_ref_runtime.py index f895bb82..23801186 100644 --- a/backend/tests/test_provider_ref_runtime.py +++ b/backend/tests/test_provider_ref_runtime.py @@ -371,11 +371,12 @@ JUDGED = "本周销售额 [[m:gmv]]。[[see:m:gmv]]增长主要来自新客首 def weekly(**report) -> dict: + # 这里测的是裁判接入:「增长主要来自新客首单」没有分析结论可挂,分析说法核对关掉,免得多重写一次 return chain( node("start", "input"), node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5}", assign_to="kpi"), node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=METRICS), - node("write", "report", instructions="写周报", **report), + node("write", "report", instructions="写周报", **{"analysis_claims": "off", **report}), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]), ) diff --git a/backend/tests/test_publish_check_api.py b/backend/tests/test_publish_check_api.py index 06d36a35..9ed653ee 100644 --- a/backend/tests/test_publish_check_api.py +++ b/backend/tests/test_publish_check_api.py @@ -38,7 +38,7 @@ def weekly(**contract_overrides) -> dict: {"id": "gmv", "name": "销售额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}, {"id": "orders", "name": "订单数", "unit": "单", "expression": "cell(nodes.fetch, 0, 'orders')"}]), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={k: v for k, v in contract.items() if v is not None}), ] diff --git a/backend/tests/test_publish_sqlcheck.py b/backend/tests/test_publish_sqlcheck.py index 4bb72e73..cfca0942 100644 --- a/backend/tests/test_publish_sqlcheck.py +++ b/backend/tests/test_publish_sqlcheck.py @@ -57,7 +57,7 @@ def weekly(source: str, sql: str) -> dict: node("card", "metrics", "周报口径卡", caliber="周报口径", metrics=[ {"id": "gmv", "name": "订单金额", "unit": "元", "expression": "cell(nodes.fetch, 0, 'gmv')"}]), node("write", "report", "报告撰写", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("done", "output", "出具", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={"report_from": "write", "metrics_from": ["card"], "required": ["gmv"], "strict": True}), ] diff --git a/backend/tests/test_report_analysis_claims.py b/backend/tests/test_report_analysis_claims.py new file mode 100644 index 00000000..7c72ddfe --- /dev/null +++ b/backend/tests/test_report_analysis_claims.py @@ -0,0 +1,298 @@ +"""报告撰写节点的分析说法核对(analysis_claims)和分析范围(analysis_scope),00-总方案 §3.5–3.6。 + +- check(缺省,问数据也是它):判断词没挂对分析结论的句子交回写作者重写一次(不按 max_repairs 反复),仍有的标在报告里, + 节点照常产出、不写缺口 +- strict:按 max_repairs 重写,仍有的写进产出的 issuance_gaps(带契约的出口降档);即使「违规处置」是判为失败也不让节点失败 +- off:不核,写作规则、文档和以前一样 +- 写作规则:有分析结论和没有时各一种说法;重写请求列出违规和修法;写作者的角色说「原因只按证据写」 +- 分析范围:这次有分析结论、取值 auto 时文档带系统写的 analysis_scope,off 或没有分析结论时不带 +- 取值写错:画布校验拦住,执行时节点报同一句话 +""" +from __future__ import annotations + +import asyncio + +import pytest +from langchain_core.messages import AIMessage +from sqlalchemy import select + +from app.analysis.testing import fake_result +from app.core import artifact_store +from app.db.base import SessionLocal +from app.db.models import Run, RunEvent +from app.engine import analysis_claims as ac +from app.engine import runner as runner_mod +from app.engine.evidence import make_eid +from app.engine.nodes import report as report_mod +from app.engine.runner import run_manager +from app.engine.schema import analysis_claims_problem, analysis_scope_problem + + +@pytest.fixture(autouse=True) +async def engine_up(): + await run_manager.setup() + yield + await run_manager.shutdown() + + +def node(nid, ntype, **config): + return {"id": nid, "type": ntype, "position": {"x": 0, "y": 0}, "data": {"label": nid, "config": config}} + + +METRICS = [{"id": "gmv", "name": "销售额", "unit": "元", "decimals": 1, "expression": "vars.kpi.gmv"}] +#: 挂了指标依据、可「主要来自」没有拆解可挂 +SOURCE = "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv]]" +PLAIN = "本周销售额 [[m:gmv]]。[[see:m:gmv]]" + + +def weekly(**report): + nodes = [ + node("start", "input", fields=[{"name": "week", "default": "2026-W37"}]), + node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5}", assign_to="kpi"), + node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=METRICS), + node("write", "report", instructions="写周报", **report), + node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]), + ] + ids = [n["id"] for n in nodes] + return {"nodes": nodes, "edges": [{"source": a, "target": b} for a, b in zip(ids, ids[1:])]} + + +def script(monkeypatch, *replies) -> list: + from app.providers import mock_model + + seen: list = [] + + def _decide(self, messages): + seen.append(list(messages)) + return AIMessage(content=replies[min(len(seen), len(replies)) - 1]) + + monkeypatch.setattr(mock_model.MockChatModel, "_decide", _decide) + return seen + + +async def finish(graph, *, run_class="exploratory") -> Run: + run = await run_manager.start(graph=graph, input_payload={}, run_class=run_class) + for _ in range(400): + await asyncio.sleep(0.05) + async with SessionLocal() as session: + row = await session.get(Run, run.id) + if row.status in ("succeeded", "failed") and row.manifest_seq is not None: + return row + raise AssertionError(f"run {run.id} 没跑完:{row.status}") + + +async def events(run_id: str, etype: str) -> list[RunEvent]: + async with SessionLocal() as session: + q = select(RunEvent).where(RunEvent.run_id == run_id, RunEvent.type == etype).order_by(RunEvent.seq) + return list((await session.execute(q)).scalars()) + + +async def checked_of(row: Run) -> tuple[dict, dict, dict]: + """(report.checked 的载荷, 文档, 报告节点产出)。""" + [checked] = await events(row.id, "report.checked") + [finished] = [e for e in await events(row.id, "node.finished") if e.node_id == "write"] + return (checked.data, artifact_store.load(checked.data["doc_artifact"]), + artifact_store.load(finished.data["artifact"])) + + +async def logs(row: Run, code: str) -> list[dict]: + return [e.data for e in await events(row.id, "log") if e.data.get("code") == code] + + +def said(violations: list[dict]) -> list[str]: + return [v["code"] for v in violations if v["code"] in ac.CODES] + + +def human_texts(messages) -> str: + return "\n".join(str(m.content) for m in messages if m.type == "human") + + +# -------------------------------------------------------------------------- +# check:重写一次,仍有的标出 +# -------------------------------------------------------------------------- + + +async def test_check_is_the_default_rewrites_once_and_flags_what_is_left(monkeypatch): + seen = script(monkeypatch, SOURCE) + row = await finish(weekly(max_repairs=3)) + assert row.status == "succeeded", row.error + assert len(seen) == 2, "check 只重写一次,不按最多重写次数反复" + first, again = human_texts(seen[0]), str(seen[1][-1].content) + assert ac.ANALYSIS_NONE_PROMPT in first, "没有分析结论时告诉写作者不下这类判断" + assert "这次没有变化拆解的结论,不能写「主要来自」" in again and ac.ANALYSIS_REPAIR_PROMPT in again + checked, doc, output = await checked_of(row) + assert doc[ac.DOC_FIELD] == {"mode": "check", "lexicon": ac.LEXICON_VERSION} + assert said(checked["violations"]) == [ac.UNCITED] and checked["analysis_claims"] == "check" + assert checked["failed"] is False and checked["repairs"] == 1 + assert output["analysis_claims"] == "check" and "issuance_gaps" not in output and "analysis_gap" not in output + [log] = await logs(row, "report_analysis_claims") + assert log["count"] == 1 and log["texts"] == ["主要来自"] and "已记为缺口" not in log["message"] + assert "已要求模型重写 1 次仍未改掉" in log["message"] and "1 处判断没挂分析结论" in log["message"] + + +async def test_a_rewrite_that_drops_the_judgement_is_accepted(monkeypatch): + seen = script(monkeypatch, SOURCE, "本周销售额 [[m:gmv]],华东下降最多。[[see:m:gmv]]") + row = await finish(weekly()) + checked, doc, output = await checked_of(row) + assert len(seen) == 2 and said(checked["violations"]) == [] and checked["ok"] is True + assert await logs(row, "report_analysis_claims") == [] + + +async def test_check_does_not_change_how_fatal_violations_repeat(monkeypatch): + seen = script(monkeypatch, "销售额 45678 元,下降主要来自华东。") + row = await finish(weekly(max_repairs=2, on_violation="flag")) + assert row.status == "succeeded" and len(seen) == 3, "裸数字照旧按最多重写次数重写" + checked, _, _ = await checked_of(row) + assert {"uncited_number", ac.UNCITED} <= {v["code"] for v in checked["violations"]} + + +async def test_check_leftovers_never_fail_the_node(monkeypatch): + script(monkeypatch, SOURCE) + row = await finish(weekly(on_violation="fail")) + assert row.status == "succeeded", row.error + checked, _, _ = await checked_of(row) + assert checked["failed"] is False and said(checked["violations"]) == [ac.UNCITED] + + +# -------------------------------------------------------------------------- +# strict:按最多重写次数重写,仍有的计入缺口 +# -------------------------------------------------------------------------- + + +async def test_strict_rewrites_up_to_max_repairs_and_records_a_gap(monkeypatch): + seen = script(monkeypatch, SOURCE) + row = await finish(weekly(analysis_claims="strict", max_repairs=2, on_violation="fail")) + assert row.status == "succeeded", "说法违规不让节点失败(不挡生成)" + assert len(seen) == 3 + checked, doc, output = await checked_of(row) + assert doc[ac.DOC_FIELD]["mode"] == "strict" and checked["failed"] is False + [gap] = output["issuance_gaps"] + assert gap == output["analysis_gap"] + assert gap.startswith("报告有 1 处分析说法未通过核对(1 处判断没挂分析结论:「主要来自」)") and "重写 2 次" in gap + [log] = await logs(row, "report_analysis_claims") + assert log["mode"] == "strict" and log["message"].endswith("已记为缺口") + + +async def test_strict_stops_once_the_judgements_are_fixed(monkeypatch): + seen = script(monkeypatch, SOURCE, PLAIN) + row = await finish(weekly(analysis_claims="strict", max_repairs=3)) + _, _, output = await checked_of(row) + assert len(seen) == 2 and "issuance_gaps" not in output + + +# -------------------------------------------------------------------------- +# off +# -------------------------------------------------------------------------- + + +async def test_off_checks_nothing_and_adds_no_rules(monkeypatch): + seen = script(monkeypatch, SOURCE) + row = await finish(weekly(analysis_claims="off")) + checked, doc, output = await checked_of(row) + assert len(seen) == 1 and ac.DOC_FIELD not in doc and said(checked["violations"]) == [] + assert ac.ANALYSIS_NONE_PROMPT not in human_texts(seen[0]) and ac.ANALYSIS_RULES_PROMPT not in human_texts(seen[0]) + assert output["analysis_claims"] == "off" and "analysis_claims" not in doc["stats"] + + +async def test_the_writer_role_asks_for_where_changes_come_from_and_evidence_for_causes(monkeypatch): + seen = script(monkeypatch, PLAIN) + await finish(weekly()) + system = str(seen[0][0].content) + assert report_mod.ROLE in system + assert "有分析结论时说清变化来自哪里" in report_mod.ROLE and "原因只按证据写" in report_mod.ROLE + assert "说清变化和原因" not in report_mod.ROLE + + +# -------------------------------------------------------------------------- +# 目录里有分析结论 +# -------------------------------------------------------------------------- + + +def a_entry(alias: str, result: dict) -> dict: + artifact = "b" * 63 + alias[-1] + return {"alias": alias, "kind": "analysis", "artifact": artifact, "eid": make_eid("analysis", artifact, {}), + "locator": {}, "label": f"{alias} {result.get('phrase')}", "result": result} + + +@pytest.fixture +def analyses(monkeypatch): + """写作目录里多几条分析结论:{A 编号: 结论}。台账里的分析结论由入口(分析卡、Agent 的分析工具)记,这里直接补进 + 目录:报告节点和出口复核按同一个 report_catalog 建目录,一处补上。""" + added: dict[str, dict] = {} + original = report_mod.report_catalog + + def catalog(state, spec, node): + out = original(state, spec, node) + out.update({alias: a_entry(alias, r) for alias, r in added.items()}) + return out + + monkeypatch.setattr(report_mod, "report_catalog", catalog) + return added + + +async def test_a_judgement_matching_its_conclusion_passes(monkeypatch, analyses): + analyses["A1"] = fake_result() + seen = script(monkeypatch, "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv,A1]]") + row = await finish(weekly()) + checked, doc, _ = await checked_of(row) + assert len(seen) == 1 and said(checked["violations"]) == [] + assert ac.ANALYSIS_RULES_PROMPT in human_texts(seen[0]) and ac.ANALYSIS_NONE_PROMPT not in human_texts(seen[0]) + + +async def test_a_judgement_that_contradicts_its_conclusion_is_handed_back(monkeypatch, analyses): + analyses["A1"] = fake_result(verdict="dispersed") + seen = script(monkeypatch, "本周销售额 [[m:gmv]],下降主要来自华东。[[see:m:gmv,A1]]") + row = await finish(weekly()) + checked, _, _ = await checked_of(row) + assert len(seen) == 2 + [miss] = [v for v in checked["violations"] if v["code"] in ac.CODES] + assert miss["code"] == ac.MISMATCH and miss["analyses"] == ["A1"] + assert "A1 判定是「销售额下降 194 万(-8.7%),分散在各地区,没有哪一段占到一半」" in str(seen[1][-1].content) + + +async def test_the_scope_is_written_only_when_there_are_conclusions(monkeypatch, analyses): + script(monkeypatch, PLAIN) + _, doc, _ = await checked_of(await finish(weekly())) + assert "analysis_scope" not in doc, "没有分析结论不写分析范围" + analyses["A1"] = fake_result() + analyses["A2"] = fake_result("baseline", None, "outside_band") + _, doc, _ = await checked_of(await finish(weekly())) + scope = doc["analysis_scope"] + assert [i["alias"] for i in scope["phenomena"]] == ["A2"] and [i["alias"] for i in scope["decomposed"]] == ["A1"] + assert scope["decomposed"][0]["dims"] == ["地区"] and scope["not_decomposed"] is None and scope["note"] + assert "analysis_scope" not in doc["markdown"] and scope["tests"] == 0 + _, doc, _ = await checked_of(await finish(weekly(analysis_scope="off"))) + assert "analysis_scope" not in doc + + +# -------------------------------------------------------------------------- +# 取值写错 +# -------------------------------------------------------------------------- + + +def test_bad_values_are_refused_by_validation(): + from app.engine.schema import GraphSpec, validate_graph + + issues = validate_graph(GraphSpec.model_validate(weekly(analysis_claims="loose", analysis_scope="always"))).issues + bad = {i.code: i for i in issues if i.code in ("report.analysis_claims_invalid", "report.analysis_scope_invalid")} + assert bad["report.analysis_claims_invalid"].level == "error" + assert bad["report.analysis_claims_invalid"].message == analysis_claims_problem("loose") + assert "「分析说法核对」只能选「不核对」、「重写一次后标出」或「重写后仍有的计入缺口」" in analysis_claims_problem("loose") + assert bad["report.analysis_scope_invalid"].message == analysis_scope_problem("always") + assert analysis_claims_problem(None) is None and analysis_claims_problem("strict") is None + + +async def test_bad_values_fail_the_node_before_any_model_call(monkeypatch): + seen = script(monkeypatch, PLAIN) + original = runner_mod.validate_graph + + def permissive(spec): + report = original(spec) + report.issues = [i for i in report.issues if i.field not in ("analysis_claims", "analysis_scope")] + report.ok = not any(i.level == "error" for i in report.issues) + return report + + monkeypatch.setattr(runner_mod, "validate_graph", permissive) + row = await finish(weekly(analysis_claims="loose")) + assert row.status == "failed" and analysis_claims_problem("loose") in (row.error or "") + assert seen == [] diff --git a/backend/tests/test_report_claims.py b/backend/tests/test_report_claims.py index 3ad71153..90960915 100644 --- a/backend/tests/test_report_claims.py +++ b/backend/tests/test_report_claims.py @@ -45,7 +45,8 @@ def weekly(**report): node("start", "input", fields=[{"name": "week", "default": "2026-W37"}]), node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5}", assign_to="kpi"), node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=METRICS), - node("write", "report", instructions="写周报", **report), + # 这里测的是结论句策略:「增长主要来自新客」没有分析结论可挂,分析说法核对关掉(见 test_report_analysis_claims.py) + node("write", "report", instructions="写周报", **{"analysis_claims": "off", **report}), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]), ] ids = [n["id"] for n in nodes] diff --git a/backend/tests/test_report_judge.py b/backend/tests/test_report_judge.py index e6589367..bb7a31e9 100644 --- a/backend/tests/test_report_judge.py +++ b/backend/tests/test_report_judge.py @@ -58,7 +58,9 @@ def weekly(*, gate=False, **report): node("fetch", "transform", mode="expression", expression="{'gmv': 45678.5}", assign_to="kpi"), node("caliber", "metrics", caliber="周报口径", caliber_version="v2", metrics=METRICS), *([node("gate", "human", mode="approve", title="确认口径")] if gate else []), - node("write", "report", instructions="写周报", **report), + # 这里测的是裁判:写作者那句「增长主要来自新客首单」没有分析结论可挂,分析说法核对关掉,免得多重写一次 + # (说法核对见 test_report_analysis_claims.py) + node("write", "report", instructions="写周报", **{"analysis_claims": "off", **report}), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}]), ] ids = [n["id"] for n in nodes] diff --git a/backend/tests/test_version_level.py b/backend/tests/test_version_level.py index ac9f7c2c..5620567f 100644 --- a/backend/tests/test_version_level.py +++ b/backend/tests/test_version_level.py @@ -52,7 +52,7 @@ def weekly() -> dict: node("card", "metrics", caliber="周报口径", metrics=[ {"id": "gmv", "name": "销售额", "unit": "元", "expression": "vars.kpi.gmv"}]), node("write", "report", instructions="写周报", - numbers="strict", on_violation="fail", claims="require_citation"), + numbers="strict", on_violation="fail", claims="require_citation", analysis_claims="strict"), node("out", "output", fields=[{"name": "周报", "value": "{{ nodes.write.text }}"}], contract={"report_from": "write", "metrics_from": ["card"], "required": ["gmv"], "strict": True}), ]