合入 W1-d 说法核对:说法表与绑定、check / strict / off、出口独立复核与文档版本、分析范围、血缘口子、G3

This commit is contained in:
ThearchyHelios
2026-10-21 14:00:07 +08:00
37 changed files with 3359 additions and 64 deletions
+2
View File
@@ -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 写的话,不是算出来的
+906
View File
@@ -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",
]
+352
View File
@@ -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"]
+3 -2
View File
@@ -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)
+2 -1
View File
@@ -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]] = {
+25 -1
View File
@@ -2869,10 +2869,17 @@ def _context(text: str, start: int, end: int) -> str:
#: 粗体:**…** 或 __…__,里面可以有标记(标记里的下划线不算收尾,[[m:refund_rate]] 很常见)
_BOLD = re.compile(r"(\*\*|__)(?P<inner>(?:\[\[" + _MARKER_GUARD + r"[^\[\]\n]*?\]\]|(?!\1)[^\n])+?)\1")
#: 方向词、因果词:没有数字也没有引用的句子,含这些词才算结论。「同比」「环比」不在里面:它们只说明
#: 跟谁比,本身不是涨跌;真正的比较结论还会带「增长」「下降」或者数字
#: 跟谁比,本身不是涨跌;真正的比较结论还会带「增长」「下降」或者数字。
#: 分析判断词(分析能力一轮,engine/analysis_claims 的说法表)也算:「主要来自」「集中在」「异常」「持续下降」「趋势」
#: 「显著」,裁判优先判这类句子(judge.claim_priority)。「主要」后面是「包括、内容、分为、有、看」这类的是在列提纲,
#: 「持续关注」「持续跟进」是建议,「趋势图」「趋势如下」是在引出图表,「集中采购」「分散风险」说的不是数据,都不算
_DIRECTIONAL = re.compile(
r"增长|增加|上升|提升|提高|上涨|下降|下滑|减少|降低|回落|下跌|反弹|超过|高于|低于|领先|落后|最高|最低"
r"|最多|最少|来自|导致|因为|由于|带动|拉动|拖累|驱动|原因|归因|贡献|占比|翻倍|持平|波动"
r"|主要(?!包括|内容|分为|分成|有|看|从|是指|指|结论|发现|观点|工作|任务|目的|目标|问题|方面)"
r"|集中(?!采购|管理|处理|展示|讨论|培训)|异常|偏离"
r"|持续(?!关注|跟踪|跟进|观察|监控|推进|优化|改进|更新)|趋势(?![图表线如::])|显著|明显高于|明显低于|大幅|激增"
r"|骤降|暴跌|飙升|新高|新低|抵消|分散(?!注意|精力|风险|投资|采购)"
r"|(?<![A-Za-z])(?:increase|decrease|grow|growth|decline|drop|rise|due to|because|driven)(?![A-Za-z])",
re.I)
#: 定义句:「同比是将本期与上年同月对比」「增长率是指……」。解释一个概念怎么算,不是对数据下结论
@@ -3052,12 +3059,15 @@ def compose_doc(
entities: bool = True,
absence: bool = False,
masked: dict[str, Any] | None = None,
analysis_claims: str | None = None,
) -> 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):
+12 -5
View File
@@ -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)}」"
+4
View File
@@ -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": "不予出具"},
+176 -17
View File
@@ -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
+93 -10
View File
@@ -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 {}),
}
+30
View File
@@ -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")
+3 -1
View File
@@ -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(
+2 -2
View File
@@ -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 }} 写一份简短的周报:先用一两句话总结本周,"
"再分点说销售额、订单、客单价和退款的变化。"),
+465
View File
@@ -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", "引出图表的话不算判断"
@@ -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"
+206
View File
@@ -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
+2 -1
View File
@@ -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}),
)
+2 -2
View File
@@ -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(
+5 -4
View File
@@ -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")
+1 -1
View File
@@ -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}),
]
+3 -2
View File
@@ -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
@@ -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 下没有可标注的"
+1 -1
View File
@@ -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:])]}
@@ -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}
+2 -1
View File
@@ -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")
@@ -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) == []
+2 -2
View File
@@ -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") == []
+2 -2
View File
@@ -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"]
+2 -1
View File
@@ -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 {})}),
+2 -1
View File
@@ -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}
+2 -1
View File
@@ -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 }}"}]),
)
+1 -1
View File
@@ -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}),
]
+1 -1
View File
@@ -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}),
]
@@ -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 == []
+2 -1
View File
@@ -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]
+3 -1
View File
@@ -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]
+1 -1
View File
@@ -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}),
]