AgentLab/docs/zh-CN/analysis.md

English | 简体中文

分析能力

这篇讲报告里的分析判断从哪来：「主要来自华东」「超出常规波动」「持续上升」「差异站得住」这类判断怎么由系统算出来、怎么写进报告、怎么核对。包括五种分析各回答什么问题、按什么标准判、算不了时怎么说，Agent 的分析工具和分析卡两个入口，报告里的引用写法，判断词的核对，报告末尾的「分析范围」，以及设置和限制。给搭建者和看报告的人看。

是什么、为什么

报告里的数字由系统照快照填进去，叙述层不做算术（见证据与出具）。可报告要说的不只是数，还有判断：变化主要来自哪里、这次算不算异常、是不是一直在涨、两组的差别是不是真的。以前这些判断由写报告的模型自己下，它挑着证据说，读的人核对不了。

分析能力把判断也收回系统：

• 判定由系统算：五种分析是平台的确定性代码，只读这次运行里交回过的查询快照，按固定的方法和阈值算出判定。模型只决定算什么（比哪两期、拆哪个维度、往哪一段下钻），改不了方法和阈值。
• 判定语由系统写：每份分析结论带一句系统按模板写好的判定语，报告引用它（[[a:A1]]），和数字一样点得开出处。写作者自己写「主要来自」「异常」这类判断时，系统逐句核对它挂没挂对应的分析结论、判定对不对得上（见分析说法核对）。
• 照实说：算不了就说为什么——历史不够、本期没过完、查询被截断、两期不可比、样本太少——不硬给结论。算不了本身也是一条结论，写作者照实写。
• 留痕：每份分析结论连同方法与版本、参数、实际用的阈值、输入的格、现查的表范围、结果和判定，存成内容寻址的工件，进证据台账、随运行封存；证据面板、报告导出、可验证报告都按同一个函数复算核对（见点开一个数看到什么）。

拆解只说明变化来自哪里，说明不了为什么。原因要有知识库原话或运行输入作依据，否则写成待核实的推测。

五种分析

每做一次分析产出一份分析结论，写作目录里按先后编成 A1、A2……（和查询的 Q1、知识库的 K1 同一套编号规则）。一份结论有：判定（判定码、点名的段、方向）、判定语、判定标准（照实际阈值写的一句）、具名的数（占比、总变化这类）、结果表、附带说明（抵消、辛普森悖论、样本少、历史新高……，最多两条接在判定语后面）。

下面括号里的阈值都是缺省值，在「设置 → 偏好设置 → 分析」里改（见分析设置）。

变化拆解

回答「变化从哪来」。三种模式：

模式	用在	怎么拆
可加	销售额、订单数这类能相加的量	按维度（一到两列）算各段对总变化的贡献和占比
比率	退款率、客单价这类比率	拆成结构变化（各段的占比变了）和各段自身的变化，两者之和精确等于比率的变化
乘积	销售额 = 订单数 × 客单价	按对数平均（LMDI）拆成各因子的贡献

• 判定：一段占总变化的一半以上（0.5）算主要来源（「主要来自华东」）；没有这样的一段、前几段合计占八成以上（0.8）算集中（段数最多是全部段数的两成，至少 2 段）；总变化不到基期的 0.5% 算基本持平；其余算分散。比率拆解判主要来自结构变化、主要来自各段自身的变化，或两者都有影响；乘积拆解判主要来自哪个因子。
• 给了总数时，各段之和要和总数对得上（按总数的书写精度容差）才判断变化来自哪里；对不上就不判，判定语写差多少。没给总数时以各段之和为总数，判定标准里写明。
• 反向的段合计超过总变化的四分之一（0.25）时附一句互相抵消了一部分；比率拆解里各段大多在降、整体却在升（或反过来）时附一句辛普森悖论的说明；分母不到 30 的段标「分母小」，不参与这个判断。
• 下钻：一次拆解里的某一段可以接着往下拆一层（华东按渠道），这一层各段之和要等于上一层那一段的值，最多下钻 3 层。下钻的查询由 Agent 自己写、只查那一段，系统按上一层那一段的值核对闭合。
• 判定语举例：「销售额下降 194（-9.2%），主要来自华东（-120，占 61.9%）」。

波动基线

回答「这次的变化大不大、算不算异常」：把本期放回它自己的历史里看。

• 输入一条按期次排的序列（日、周、月、季）。缺省比的是和上一期比的变化率，日数据和上周同一天比，避开星期效应；存量、比率可以比值本身；要同比就和 52 周前、12 个月前比，历史要相应够长。
• 用历史的中位数和中位绝对偏差（稳健标准差 = 1.4826 × 中位绝对偏差）：本期和中位数的差不到 2 倍稳健标准差算常规波动，2 到 3 倍算超出，3 倍以上算明显超出。用中位数不用均值：促销周这类极端值会把均值和标准差拉宽，正常的周、异常的周都显得不异常。
• 历史至少 8 期、最多用 52 期；本期是历史里最高或最低的，附一句历史新高、新低。
• 判定语举例：「销售额本期变化 -15.8%，明显超出过去 24 周的常规波动范围（-0.5% 至 +0.4%）；本期的销售额是过去 24 周里最低的」。

趋势判断

回答「是在持续变，还是一次波动」。

• 取最后连着的一段（至少 6 期）：Mann–Kendall 检验的双侧 p 值小于 0.05 时，按 Theil–Sen 斜率的正负判上升或下降，否则判没有明显趋势。末尾连续 3 期以上同向时，判定语接「已连续 3 周下降」，和趋势反向时写「但最近已连续 3 周上升」。
• Mann–Kendall 假设各期独立，业务序列常有自相关，p 会偏小，所以判定语只说「呈上升趋势」，不说「显著上升」。日数据附一句星期效应，建议按周汇总。
• 判定语举例：「过去 12 周线上销售额呈上升趋势（每周约 +2.1%），已连续 4 周上升」。

差异检验

回答「这两组（或同一组的两期）真的不一样，还是样本波动」。

• 比率（转化率、退款率）给成功数和试验数：每组算 Wilson 区间；各格的期望频数都不小于 5 时用合并比例的 z 检验，否则用 Fisher 精确检验。
• 均值给每组的均值、标准差、样本数，或者合计、平方和、样本数（SQLite 没有标准差函数时这样写），用 Welch t 检验；也可以给逐行的值（不超过 1000 行、没截断），系统自己算，另做一遍去掉最远那个值的敏感性检查。
• 双侧 p 值小于 0.05 算差异站得住；一次比了好几对时按 Holm 校正。均值有一组样本不到 30、比率用了 Fisher 时附一句样本少。
• 判定语不出现「p 值」「显著性」这些词：站得住写「差异站得住」，否则写「差异可能只是样本波动（样本量 230、40）」。p 值和区间在结果表和证据面板里。

可比性检查

回答「这两期能不能直接比」。每项判通过、提醒、不通过或核对不了：

项	怎么判
同口径	两份查询只差日期才算同口径；结构不同，或者除了日期还筛了别的（华东对华南），不通过
窗口长度	两期天数一样；可加的流量不一样就不通过，比率、存量只提醒
整期	本期过完了、表里的数据到了；流量没到齐不通过（「本期只有 3 天数据」），其余提醒
星期构成	按天取、天数不是 7 的倍数时，两期的周末天数要一样，不一样提醒
数据问题	查询区间里没有数据不通过，SQL 检查有错误提醒

全部通过（或核对不了）判可比，只有提醒判有条件可比，有一项不通过判不可比。核对不了的项不判不可比，判定语里写明哪几项核对不了。表的实际日期范围现查（只读、限时、遮罩列不查，失败退回剖析记下的范围），查到的范围记进结论，复算按记下的值。

变化拆解给的是两份查询时，先自动做一次可比性检查；波动基线、趋势判断和单份查询的变化拆解看本期齐不齐时，用的是其中「整期」那一项。口径卡里一个指标用到两份同形、只差日期的查询（本周对上周）时，也自动做一次，结果挂在指标上（见口径卡）。

跨源对账与伴随异动

在五种单源分析之外，跨源本体穿透提供两项跨指标确定性算子与一项数据源健康探针：

• 跨源对账（reconcile）：核对互为 reconciles_with 镜像的两套口径或两份查询按对齐键逐行的差额。支持 scale 量纲换算（如千瓦时与兆瓦时换算 1000）与绝对/相对容差，产出 aligned（对账一致）、diverged（对账偏离，点名超差实体段）或 missing_counterpart（单边缺失）。
• 伴随异动（cochange）：核对主指标与 upstream_driver 上游指标在同一时间序列与滞后窗口（lag_periods 为 0 至 3 期）上是否同步超出稳健波动基线（中位数与中位绝对偏差），并给出 Spearman 秩相关描述量，产出 co_anomalous（同期同步异动）、target_normal（上游平稳，排除该上游驱动）或 opposite_move。判定语与分析说法核对强制把 cochange 限定为统计同步异动，没有知识库明确规则依据时严禁写成「导致 / 引起 / 造成」。
• 数据源健康核查（source_health）：只读检查目标数据源或口径底层物理表的新鲜度断更（date_stalled）、日期断档（date_gap）、近期行数骤降（volume_drop）及目录外新增编码（codes_new），封存为 H1、H2…… 工件，报告可用 [[h:H1]] 与 [[see:H1]] 引用并在证据抽屉复核。

算不了的时候

算不了不让 Agent、节点失败，记成一条结论，判定语写「波动基线没有做成：历史只有 5 期，至少要 8 期」这样的一句，进台账、能引用、能核对：

原因	什么时候
截断	输入的查询只取回了前一部分行，各段之和不是完整的和
段太少	拆开后不到 2 段
历史不够	有效的历史期数不到最少期数
本期不完整	本期没过完、数据没到、不到整周，或者查询只取了本期的一部分
缺期	本期和比较期之间缺期；趋势判断用的最后几期不连着
期次认不出	期次列的写法认不出（带时刻的、写法混着的）
比较期为 0	算不了变化率
有值不为正	乘积拆解要求各值都为正
两边不是同一个量	两份查询结构不同，不是同一个量的两期，不拆
拿不到 p 值	差异检验一对都算不出 p 值（两组各只有 1 个样本、样本量为 0）
上一层没做成、这次的数据里没有	分析卡里下钻的上一层算不了，或者这期的数据里没有要用的期次、段、组、总数那一格

调用写错不记结论：列不存在、拿遮罩列当维度或度量、比率当成可加的量、同一段同一期有好几行、参数写错、这个 Agent 这次执行的分析次数用完了。Agent 收到一句怎么改的说明，改了再调；分析卡里是模板写错了，整张卡失败并说清是哪一项。

期次认这几种写法：日期、YYYY-MM、YYYY-Www、YYYY-Qn、整数序号。按周汇总时，期次最好在 SQL 里由日期列算出来，写每周第一天的日期，或 ISO 周 YYYY-Www。同样写成 2026-W42，SQLite 的 %W、MySQL 的 %u 算出的和 ISO 周落在不同的日子上，系统按 SQL 里的格式串认出算法、算出真实的起止；直接取表里现成的周号文本时认不出算法，本期齐不齐核对不了。

两个入口

两个入口共用同一套分析、同一种结论、同一张判定语表。

Agent 的分析工具

问数据和画布上的 agent 可以绑五个分析工具：analysis_decompose（变化拆解）、analysis_baseline（波动基线）、analysis_trend（趋势判断）、analysis_differ（差异检验）、analysis_comparable（可比性检查）。要看了数才知道拆哪个维度时用它。

• 参数只有「算什么」：分析本节点查过的哪个结果（Q3，和交回模型的「【证据 Q3】」同一个编号）、各列的角色、比哪两期、总数那两格、下钻的上一层、度量的叫法，和一句这次在验证什么（只在证据面板显示，不进报告正文）。没有任何阈值参数。
• 绑了任一个，平台就把内置的分析方法注入 agent 的系统提示：先按问题定基期，做可比性检查和波动基线，再拆因子与结构、按维度由粗到细拆，找到主要来源再下钻一层；拆了不集中也是结论；不作因果断言；算不了照实说；最后列出做过的分析和判定。方法随版本升级。
• 交回 agent 的是「【分析 A2】」加判定、判定语、关键的数、附带说明或算不了的原因；整份结论进证据台账。
• 每个 Agent 每次执行最多分析 12 次、最多下钻 3 层。
• 分析工具只分析绑了它的 agent 自己查过的结果，不能放进「调用工具」节点（模板里要固定做的分析用分析卡）。协作团队的成员也能用，但结论不进证据台账，报告引用不了。
• 使用者（user 角色）的问数据里也能用：分析工具不查库，只读已经按遮罩处理过的查询结果，遮罩列不当维度、不当度量。

分析卡

分析卡（analysis 节点，和口径卡平级）对上游查询节点的结果固定做几项分析，用于模板里每次都要做的分析，比如周报的异动：这一周的变化在不在常规波动范围内、主要来自哪个地区。

• 每一项写明分析方法和模式、要分析哪个上游查询节点、参数和这一项在验证什么。输入只能是调用数据库查询工具的「调用工具」节点或「合并查询」，而且连在分析卡之前；Agent 可能查了好几次，不能当输入。参数和分析工具的一样，可以用 {{ input.x }} 按运行输入选期次。
• 阈值不写在分析项里。模板要固定阈值时写在卡上的「阈值覆盖」里，随版本固定；它和这次运行的分析设置冲突时，卡失败并说清冲突在哪。
• 产出 nodes.<卡>.results.<项>：状态、判定码、方向、具名的数、判定语。下游条件分支可以按判定走，比如超出常规波动就转人工。
• 一项算不了不让卡失败，那一项照实记成算不了，接着做下一项。
• 分析卡的结果不作口径卡的输入：口径卡读它，按追不到原始数据处理。指标在口径卡里按格从查询结果取，分析结论在报告里直接引用。
• 受管级别要求分析卡的输入是调用数据库查询工具的「调用工具」节点或「合并查询」，发布时就能确定分析的是平台执行的查询。
• 运行对比按分析卡的节点和项对齐，列出两次的判定（见运行对比）。

内置模板 ⑪「异动分析（可追溯）」就是这样搭的：整体按周、按地区两周取数 → 分析卡（波动基线、带总数的变化拆解）→ 报告撰写 → 出具，拿来就能按受管级别发布（见内置模板）。

在报告里引用

[[a:A1]]                                    A1 的判定语，由系统按判定渲染，一个点得开的片段
[[a:A1.top_share|pct]]                      A1 的一个具名的数，换算后缀同 [[m:]]
[[v:A1.r0.share]]                           A1 结果表里的一格
[[table:A1 cols=地区,delta,share rows=0-4]]  A1 的结果表
[[see:A1]]                                  这句的依据，挂在句末，不渲染

• 写作目录里「分析结论」一段列出每份结论的编号、判定语、具名的数、结果表的前 10 段、附带说明或算不了的原因。
• 分析结论里的占比、变化率由系统按百分数显示（[[a:A1.top_share]]、[[v:A1.r0.share]] 写出来是 62.0%），比率的变化按百分点（1.2 个百分点），写作者照常引用、不用自己写换算；自己写了换算的照他的。
• 分析卡的结论总能引用。受管级别的正式出具里，Agent 用分析工具现场做的分析和它查的格同一个规矩：出具契约开了「单元格引用」才能引用（句末依据照样能挂）。
• 判定语里的度量叫法是 Agent 或模板给的，系统先去掉里面的数字、百分号、单位和引用标记，截到 20 字以内：系统写的字里不会夹带模型写的数。

分析说法核对

报告撰写节点的「分析说法核对」（analysis_claims）逐句核对判断词：确定的词表加绑定，不调用模型。

判断词的类	例子	要挂的分析结论和判定
来源	主要来自、集中在、拖累、带动、贡献最大	变化拆解，判主要来源或集中；点名的段要在判定里，说拖累的那一段要在降
分散、抵消、结构	分散在各地区、此消彼长、结构变化	变化拆解，判分散、有抵消、主要来自结构变化
异常、新高新低、正常	异常、大幅、激增、历史新高、正常波动	波动基线，判超出或明显超出（方向对得上）、新高新低、常规波动
趋势、无趋势	持续上升、连续三周下降、没有明显趋势	趋势判断，方向、连续期数对得上
差异、无差异	显著高于、确实更低、差异不大	差异检验，差异站得住（方向对得上）或可能只是样本波动
因果	因为、由于、导致、受…影响	同一句有知识库原话或运行输入作依据，或者写成推测（可能、待核实）

• 一句的依据是句中的 [[a:…]]、[[v:A…]]、[[table:A…]] 和句末的 [[see:A…]]。否定会翻到反面：「并不异常」按正常核。
• 不核的：说的是构成而不是变化（「本周订单主要来自线上渠道」）、建议和计划、业务状态里的「异常」（「部分订单异常」）；知识库原话、系统渲染的判定语、标题和表格。
• 来源和因果的分界：「下降主要由华东造成」挂了按地区的拆解、点名的是拆解里的段，按来源核，这是记账意义上的「来自」；「由于促销结束导致下降」点名的不是段，按因果核。
• 违规三种：判断词没挂对应的分析结论；挂了，但判定、点名的段或方向对不上（挂了算不了的结论也算）；原因没有依据。

取值	做法
check（缺省，问数据也是它）	交回写作者重写一次，仍有的标在报告里，不影响出具档位
strict	按最多重写次数重写，仍有的计入出具缺口、出具降档；受管级别要求它（门禁 G3）
off	不核

• 写作目录里有分析结论时，写作者被告知判断照判定写、最好直接引用判定语；没有时被告知不下这类判断，只陈述数字和变化。
• 引用模式的出口独立再核一遍，和组装时用同一个核对。报告文档记下按哪种处置、哪一版说法表核：只有带这一项的文档在复核时核这一项，升级前的报告复核结果不变。
• 宁可漏报：只收强判断词。漏掉的细处由结论句裁判兜底（见结论句）；裁判摘录里有分析结论时，裁判另被告知判定是系统算的，只判句子说得对不对。

分析范围

报告用到了分析结论（这次运行有分析结论）时，系统在报告末尾附一段「分析范围」。写作者改不了，随文档封存，编号点得开：

• 现象：可比性检查、波动基线、趋势判断的判定语。
• 拆过：每份变化拆解按下钻链列出维度和判定。
• 排除：判定为分散的拆解、差异可能只是样本波动的检验——拆了没发现集中也是结论。
• 算不了：各项算不了的原因。
• 没拆：候选维度里没拆过的。候选维度从数据目录确定地算：拆解所用查询里的事实表上标成属性、状态，不遮罩、有码值表（取值不超过 50 个，或者已列全）的列，加上它关联的维度表上同样的列。拆解用的列对不上目录时只说候选维度核对不了，不乱列。
• 检验：这次做了几次差异检验，是否已按次数校正。

Agent 写的「这次在验证什么」不进这一段，只在证据面板显示。报告撰写节点的「分析范围」（analysis_scope）缺省是有分析结论时附上，可以设成不附。

设置

「设置 → 偏好设置 → 分析」里改判定用的阈值、Agent 每次执行最多分析几次、最多下钻几层、列出前几段，各项的叫法和缺省见分析设置。

• 发起运行时把这一组快照进运行（只在图里有分析卡、或者 agent 绑了分析工具时），恢复和接着跑沿用同一份。
• Agent 改不了阈值：分析工具的参数里没有阈值。模板可以在分析卡上写阈值覆盖。
• 每份结论记下实际用的阈值，判定标准照这些值写出来，例如「一段占总变化的一半以上算主要来源」。

限制

• 这一轮没有：预测；相关分析；维度层级进数据目录；数值列的剖析；双盲复算、反方审稿、审批质询的核查 agent 使用分析工具；分析结论参与口径账本的比对和召回（分析结论里的数不标口径，见口径账本）。
• 趋势判断假设各期独立，自相关的序列 p 会偏小。
• 候选维度只认码值表：剖析目前不记每列的取值数，没有码值表的属性列不进候选。
• 说法表只收强判断词，换个说法可能漏过，漏过的由结论句裁判和读报告的人兜底。
• 协作团队成员做的分析不进证据台账，报告引用不了。