mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 00:21:58 +00:00
ThearchyHelios
206 lines
21 KiB
Markdown
206 lines
21 KiB
Markdown
[English](../en/analysis.md) | 简体中文
|
||
|
||
# 分析能力
|
||
|
||
这篇讲报告里的分析判断从哪来：「主要来自华东」「超出常规波动」「持续上升」「差异站得住」这类判断怎么由系统算出来、怎么写进报告、怎么核对。包括五种分析各回答什么问题、按什么标准判、算不了时怎么说，Agent 的分析工具和分析卡两个入口，报告里的引用写法，判断词的核对，报告末尾的「分析范围」，以及设置和限制。给搭建者和看报告的人看。
|
||
|
||
## 是什么、为什么
|
||
|
||
报告里的数字由系统照快照填进去，叙述层不做算术（见[证据与出具](evidence.md#基本思路)）。可报告要说的不只是数，还有判断：变化主要来自哪里、这次算不算异常、是不是一直在涨、两组的差别是不是真的。以前这些判断由写报告的模型自己下，它挑着证据说，读的人核对不了。
|
||
|
||
分析能力把判断也收回系统：
|
||
|
||
- **判定由系统算**：五种分析是平台的确定性代码，只读这次运行里交回过的查询快照，按固定的方法和阈值算出判定。模型只决定算什么（比哪两期、拆哪个维度、往哪一段下钻），改不了方法和阈值。
|
||
- **判定语由系统写**：每份分析结论带一句系统按模板写好的判定语，报告引用它（`[[a:A1]]`），和数字一样点得开出处。写作者自己写「主要来自」「异常」这类判断时，系统逐句核对它挂没挂对应的分析结论、判定对不对得上（见[分析说法核对](#分析说法核对)）。
|
||
- **照实说**：算不了就说为什么——历史不够、本期没过完、查询被截断、两期不可比、样本太少——不硬给结论。算不了本身也是一条结论，写作者照实写。
|
||
- **留痕**：每份分析结论连同方法与版本、参数、实际用的阈值、输入的格、现查的表范围、结果和判定，存成内容寻址的工件，进证据台账、随运行封存；证据面板、报告导出、可验证报告都按同一个函数复算核对（见[点开一个数看到什么](evidence.md#点开一个数看到什么)）。
|
||
|
||
拆解只说明变化来自哪里，说明不了为什么。原因要有知识库原话或运行输入作依据，否则写成待核实的推测。
|
||
|
||
## 五种分析
|
||
|
||
每做一次分析产出一份分析结论，写作目录里按先后编成 A1、A2……（和查询的 Q1、知识库的 K1 同一套编号规则）。一份结论有：判定（判定码、点名的段、方向）、判定语、判定标准（照实际阈值写的一句）、具名的数（占比、总变化这类）、结果表、附带说明（抵消、辛普森悖论、样本少、历史新高……，最多两条接在判定语后面）。
|
||
|
||
下面括号里的阈值都是缺省值，在「设置 → 偏好设置 → 分析」里改（见[分析设置](configuration.md#分析设置)）。
|
||
|
||
### 变化拆解
|
||
|
||
回答「变化从哪来」。三种模式：
|
||
|
||
| 模式 | 用在 | 怎么拆 |
|
||
|---|---|---|
|
||
| 可加 | 销售额、订单数这类能相加的量 | 按维度（一到两列）算各段对总变化的贡献和占比 |
|
||
| 比率 | 退款率、客单价这类比率 | 拆成结构变化（各段的占比变了）和各段自身的变化，两者之和精确等于比率的变化 |
|
||
| 乘积 | 销售额 = 订单数 × 客单价 | 按对数平均（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 检查有错误提醒 |
|
||
|
||
全部通过（或核对不了）判可比，只有提醒判有条件可比，有一项不通过判不可比。核对不了的项不判不可比，判定语里写明哪几项核对不了。表的实际日期范围现查（只读、限时、遮罩列不查，失败退回剖析记下的范围），查到的范围记进结论，复算按记下的值。
|
||
|
||
变化拆解给的是两份查询时，先自动做一次可比性检查；波动基线、趋势判断和单份查询的变化拆解看本期齐不齐时，用的是其中「整期」那一项。口径卡里一个指标用到两份同形、只差日期的查询（本周对上周）时，也自动做一次，结果挂在指标上（见[口径卡](evidence.md#口径卡)）。
|
||
|
||
## 算不了的时候
|
||
|
||
算不了不让 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.<项>`：状态、判定码、方向、具名的数、判定语。下游条件分支可以按判定走，比如超出常规波动就转人工。
|
||
- 一项算不了不让卡失败，那一项照实记成算不了，接着做下一项。
|
||
- 分析卡的结果不作口径卡的输入：口径卡读它，按追不到原始数据处理。指标在口径卡里按格从查询结果取，分析结论在报告里直接引用。
|
||
- 受管级别要求分析卡的输入是调用数据库查询工具的「调用工具」节点或「合并查询」，发布时就能确定分析的是平台执行的查询。
|
||
- 运行对比按分析卡的节点和项对齐，列出两次的判定（见[运行对比](evidence.md#运行对比)）。
|
||
|
||
内置模板 ⑪「异动分析（可追溯）」就是这样搭的：整体按周、按地区两周取数 → 分析卡（波动基线、带总数的变化拆解）→ 报告撰写 → 出具，拿来就能按受管级别发布（见[内置模板](workflows.md#内置模板)）。
|
||
|
||
## 在报告里引用
|
||
|
||
```
|
||
[[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` | 不核 |
|
||
|
||
- 写作目录里有分析结论时，写作者被告知判断照判定写、最好直接引用判定语；没有时被告知不下这类判断，只陈述数字和变化。
|
||
- 引用模式的出口独立再核一遍，和组装时用同一个核对。报告文档记下按哪种处置、哪一版说法表核：只有带这一项的文档在复核时核这一项，升级前的报告复核结果不变。
|
||
- 宁可漏报：只收强判断词。漏掉的细处由结论句裁判兜底（见[结论句](evidence.md#结论句)）；裁判摘录里有分析结论时，裁判另被告知判定是系统算的，只判句子说得对不对。
|
||
|
||
## 分析范围
|
||
|
||
报告用到了分析结论（这次运行有分析结论）时，系统在报告末尾附一段「分析范围」。写作者改不了，随文档封存，编号点得开：
|
||
|
||
- **现象**：可比性检查、波动基线、趋势判断的判定语。
|
||
- **拆过**：每份变化拆解按下钻链列出维度和判定。
|
||
- **排除**：判定为分散的拆解、差异可能只是样本波动的检验——拆了没发现集中也是结论。
|
||
- **算不了**：各项算不了的原因。
|
||
- **没拆**：候选维度里没拆过的。候选维度从数据目录确定地算：拆解所用查询里的事实表上标成属性、状态，不遮罩、有码值表（取值不超过 50 个，或者已列全）的列，加上它关联的维度表上同样的列。拆解用的列对不上目录时只说候选维度核对不了，不乱列。
|
||
- **检验**：这次做了几次差异检验，是否已按次数校正。
|
||
|
||
Agent 写的「这次在验证什么」不进这一段，只在证据面板显示。报告撰写节点的「分析范围」（`analysis_scope`）缺省是有分析结论时附上，可以设成不附。
|
||
|
||
## 设置
|
||
|
||
「设置 → 偏好设置 → 分析」里改判定用的阈值、Agent 每次执行最多分析几次、最多下钻几层、列出前几段，各项的叫法和缺省见[分析设置](configuration.md#分析设置)。
|
||
|
||
- 发起运行时把这一组快照进运行（只在图里有分析卡、或者 agent 绑了分析工具时），恢复和接着跑沿用同一份。
|
||
- Agent 改不了阈值：分析工具的参数里没有阈值。模板可以在分析卡上写阈值覆盖。
|
||
- 每份结论记下实际用的阈值，判定标准照这些值写出来，例如「一段占总变化的一半以上算主要来源」。
|
||
|
||
## 限制
|
||
|
||
- 这一轮没有：预测；相关分析；维度层级进数据目录；数值列的剖析；双盲复算、反方审稿、审批质询的核查 agent 使用分析工具；分析结论参与口径账本的比对和召回（分析结论里的数不标口径，见[口径账本](evaluation-and-ledger.md#口径账本)）。
|
||
- 趋势判断假设各期独立，自相关的序列 p 会偏小。
|
||
- 候选维度只认码值表：剖析目前不记每列的取值数，没有码值表的属性列不进候选。
|
||
- 说法表只收强判断词，换个说法可能漏过，漏过的由结论句裁判和读报告的人兜底。
|
||
- 协作团队成员做的分析不进证据台账，报告引用不了。
|