mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-20 21:22:00 +00:00
完善口径管理、主动调查与后台任务,修复通用问题
- 完善口径编辑、只读试运行、统一质量验证与执行语义指纹 - 增加可执行指标约束、有预算的主动调查和过程评测 - 提取发布检查、证据读取与起草服务,支持任务停止、重试和检查点恢复 - 增加版本传递影响分析,修复并发覆盖、敏感值遮罩、异常评分及页面状态问题 - 修复 SQLite 复合查询追溯和 microVM 可选依赖缺失处理 - 纳入当前设计文档及部署配置调整 验证:相关主回归 3822 项通过,4 项跳过、8 项预期失败;补充回归通过。 前端构建、文案检查及 git diff --check 通过。 全量检查仍有环境权限、PostgreSQL 可选依赖和既有部署配置、SQLite 文件基线差异导致的未通过项。
This commit is contained in:
@@ -0,0 +1,234 @@
|
||||
# 分析能力一轮总方案:算、想、核
|
||||
|
||||
> 状态:已拍板(2026-10-21):六项能力 + 评测一轮做完;问数据里的说法核对打回重写一次,仍不过就标出。开工。代码基准 main `9e5debfb`。
|
||||
> 依据:五路只读调研(结论落到文件:行号)。细案 01-算子与判定.md 定算子、判定、说法表和阈值;本篇定范围、理念、跨块决定、接入、分包与关口,冲突以本篇为准。真实库名、表名、计数都不进本文;示例、测试、验收一律用虚构零售库。
|
||||
|
||||
## 0. 范围
|
||||
|
||||
| 块 | 编号 | 一句话 |
|
||||
|---|---|---|
|
||||
| 算 | ① 可比性检查 | 比两期之前先确认能比:只差日期、窗口一样长、是整期、星期构成相同 |
|
||||
| 算 | ② 变化拆解 | 变化从哪来:可加按维度算贡献(闭合核对)、比率拆结构与自身、乘积拆因子、逐层下钻 |
|
||||
| 算 | ③ 放回历史看 | 波动基线(算不算异常)+ 趋势(是不是持续) |
|
||||
| 算 | ④ 差异与样本量 | 两组 / 两期的差异站不站得住:区间、检验、小样本、单值敏感、多重比较校正 |
|
||||
| 想 | ⑤ 分析计划与假设台账 | 分析型问数、平台内置的分析方法、候选维度来自目录、系统写「查了什么、排除了什么、哪些没查」 |
|
||||
| 核 | ⑥ 分析说法核对 | 判断词要挂对应的分析结论且强度对得上;判定语由系统渲染;因果词没依据标推测 |
|
||||
| 配套 | 评测 | 两种新期望(贡献、判定),期望由期望 SQL + 同一套算子算出;埋了效应的虚构题集 |
|
||||
| 配套 | 修口子 | 引用模式下被引指标的输入追不到原始数据时,受管级记缺口,其余标注 |
|
||||
|
||||
不在本轮:预测;相关分析;维度层级进目录;数值列剖析;核查 agent(双盲、反方、质询)使用分析工具;分析结论参与口径账本比对与召回。
|
||||
|
||||
## 1. 调研结论(为什么要做)
|
||||
|
||||
- **能算的太少**:报告里站得住的数只来自 SQL 返回的格、口径卡的白名单标量式(`engine/expressions.py:528`,没有分组、按键排名、方差、检验)、运行输入和知识库原话。沙箱只有标准库(`sandbox/interpreter.py`),算出的数按设计不能引用(`engine/evidence.py:758`)。
|
||||
- **分析结论没有来源**:维度归因只在两次运行对比里(`engine/compare.py`),不进台账;`data/value_drift.py` 只看目录的行数和码值。
|
||||
- **要求说原因、却不给原因**:写作者的角色是「挑重点、组织结构、说清变化和原因」(`engine/nodes/report.py:107`);裁判被告知不要复算、只看写作者挂的证据(`engine/judge.py:154`),挑过的证据照样过;问数据建图明写不加反方审稿、claims 不用写(`api/copilot.py:411`)。开发库 160 轮问数据里反方审稿、双盲复算一次都没出现。
|
||||
- **没有方法**:建图和 agent 提示词里没有基期对比、拆解、下钻、假设验证;种子里的「结构化分析」Skill 从没被挂过。
|
||||
- **量不出来**:评测「为什么」只能写 text 要点、不计分(`eval/cases.py:9`)。
|
||||
|
||||
## 2. 守住的理念
|
||||
|
||||
- **照实说**:算不了就说为什么(截断、不闭合、历史不够、本期不完整、不可比、样本小),不硬给结论;判定语写出判定标准。
|
||||
- **留痕**:每份分析结论是内容寻址的工件,记方法版本、参数、阈值、输入格、现查的表范围、结果、判定;进证据台账、随运行封存、能复算。
|
||||
- **不挡生成**:算不了是一条结论,不让 agent、节点失败;说法核对在问数据里只重写一次、仍不过就标出。
|
||||
- **只读与遮罩**:算子只读快照,唯一的现查(表的日期范围)走 data/coverage 的只读探查;遮罩列不当维度、不当度量。
|
||||
- **一种说法**:一套算子、一种结论形状、一个证据种类、一张判定语表、一张说法表;问数据(agent 工具)和模板(分析卡)两个入口共用。
|
||||
- **模板定骨架、agent 填关节**:模板里分析卡固定做哪些分析;问数据里 agent 运行时决定拆哪个维度,但方法和阈值由平台定。
|
||||
- **不可回退,照旧**:叙述层无算术;不做「从指标定义编译 SQL」的语义层;数据目录只放事实,口径公式在口径卡里;口径升版是被迫处置事件。本轮再往前一步:**叙述层也不下分析判定**——「主要来自」「超出常规波动」这类判定和数字一样由系统渲染,写作者只引用。
|
||||
|
||||
## 3. 设计
|
||||
|
||||
### 3.1 分析结论(契约)
|
||||
|
||||
形状见细案 01 §1。要点:kind `analysis_result` 工件、台账 kind `analysis`、写作目录编号 A1…;纯函数可复算;判定语、具名标量、结果表三种引用面。契约放在 `app/analysis/contract.py`(骨架提交),各包按它写。
|
||||
|
||||
### 3.2 两个入口
|
||||
|
||||
**agent 分析工具**(问数据、画布上的 agent):五个平台工具 `analysis_decompose`、`analysis_baseline`、`analysis_trend`、`analysis_differ`、`analysis_comparable`。
|
||||
|
||||
- 参数只有「算什么」:引用本节点查过的结果(`query: "Q3"`,和交回模型的「【证据 Q3】」同一个编号)、列的角色、期次、`headline`、`parent`、`label`、`hypothesis`;没有阈值参数。
|
||||
- 工具建在查询列表之前(`engine/nodes/llm.py:428` 早于 `:442`),所以经 `ToolContext.extra` 传一个可变的「本节点查询」容器(同 `MASKED_VALUES_KEY` 的做法,`tools/datasource.py:56`),查一次往里放一次。
|
||||
- 交回 agent:判定语、关键数、caveats、算不了的原因、编号「【分析 A2】」;台账记 kind `analysis`(`_record_call` 的写法,`engine/nodes/llm.py:871-912`)。结果确定、落成工件(tool_step 进 checkpoint,续跑回放同一份)。
|
||||
- `ToolSpec` 加 `guide` 字段(`tools/registry.py:58`),绑了任一分析工具就把平台的「分析方法」注入 system(`engine/nodes/llm.py:_build_messages:113-141`,supervisor 成员在 `engine/nodes/multi.py:329`),同一份只注入一次。不用 Skill:Skill 是用户可改、可停用的库里的行,seed 只在同名不存在时插入(`seed.py:344`),平台方法要随代码升版。
|
||||
- `is_platform_query`(`capabilities/registry.py:305`)不认分析工具:它不查库。使用者的问数据白名单(`auth/chat_policy.py:35`)加上分析工具。
|
||||
|
||||
**分析卡**(节点类型 `analysis`,和口径卡平级):`items: [{id, op, mode, from: <tool / merge 节点 id>, params...}]`,可写阈值覆盖(写进图、随版本固定)。按合并查询节点的做法从 `state.nodes` 取快照 id、load 复验(`engine/nodes/merge.py:48-79`)。产出 `nodes.<id>.results.<item>` = {status, verdict, values, phrase},下游 branch 能按判定分支(周报「超出常规波动就转人工」)。登记处按 merge 节点的先例(细案见 §5 W1-c 清单)。
|
||||
|
||||
### 3.3 证据接入
|
||||
|
||||
- 台账循环(`build_catalog`,`engine/evidence.py:937-976`)加 A 计数器;`report_catalog` 的 evidence_from 过滤(`engine/nodes/report.py:153`)放行 analysis。
|
||||
- 引用:`[[a:A3]]` 判定语(一个可点片段),`[[a:A3.top_share|pct]]` 具名标量,`[[v:A3.r0.share]]`、`[[table:A3 cols=… rows=…]]` 结果表,`[[see:A3]]` 句末依据。改 `_CELL_REF`、`_ROW_REF` 认 A,`_query_entry` 放行 kind analysis,`_Snapshots` 加取 A 结果表的适配;只认 kind query 的几处(`_header_masks`、`_text_names`、`_fields_prompt`、`masked_cells`)逐个过一遍。
|
||||
- 写作目录加「分析结论」一段:编号、判定语、具名标量、表的前 `table_top_k` 行、caveats、算不了的原因,外加怎么引用、说法规则一句。
|
||||
- 出处链(`api/evidence.py:_chain:918`)加「分析」一步:判定与判定标准 → 方法与阈值 → 计算(结果表、关键数的代入式,如「占比 = 华东变化 / 总变化 = −120 / −194」)→ 输入(落到 Q 的格,闭合核对对着 headline)→ 复算 → 封存。证据图(`_graph_of:477`)加「派生自」的边。
|
||||
- 审计、导出 HTML(`report_export/build.py`、`runtime.js` 的 PARTS)、可验证报告(`bundle/build.py` 的 `_CITED_KINDS`、`_card_input_queries`;`verifier.js` 的 KIND_LABEL、引用链、`checkNumber`)都认 A,带上结论工件和它的输入快照;浏览器里只核哈希、展示服务端的复算结果,不在 JS 里重写统计。
|
||||
- 血缘:分析结论的输入只能是本次运行台账里 kind query 的快照(解析器只认它们),复算即血缘:输入哈希都核对得上、复算逐字段相同才算追到。分析卡的结果**不作为口径卡的输入**(口径卡读 `nodes.<分析卡>.results` 按「追不到原始数据」处理,受管级静态检查给出提示)——分析是叙述的依据,不是口径的原料,见 D16。写死 `("tool_cell", "agent_field")` 的几处(`api/evidence.py:1026/1713`、`bundle/build.py:1040`、`engine/judge.py:527`、`engine/recompute.py:401/427/534/590`、`engine/nodes/dual_check.py:99`、`ledger/labels.py:58`)不用改。
|
||||
- 裁判:`_excerpt` 加 analysis 一支(方法、判定、关键数、判定标准、输入 SQL),`_candidate`、`_query_alias`、`_judge_loader` 同步。
|
||||
- 口径账本:分析结论里的数不和口径比对(它们是派生的),摘要行不计它们;前端 `LedgerTurn.tsx:30` 只认四种标签,服务端不新增标签。
|
||||
|
||||
### 3.4 可比性挂在哪
|
||||
|
||||
1. agent 单独调用 `analysis_comparable`。
|
||||
2. decompose 两份快照时、baseline / trend 判本期完整时自动做。
|
||||
3. **口径卡**:一个指标的表达式用到两份不同查询快照里的格、而且两份 SQL 同形只差字面量(本周 vs 上周)时,自动做可比性检查,结果挂在指标上(指标条目加 `comparability`)。写作目录照实提醒;带契约的出口:`incomparable` 记缺口降档(同 sql_check_failed),`conditional` 只标注。两份 SQL 结构不同(退款额 / 销售额)不是同一个量的两期,不查。
|
||||
|
||||
### 3.5 分析说法核对
|
||||
|
||||
- 说法表、否定、来源与因果的分界、违规代码与处置见细案 01 §9。实现在 `engine/analysis_claims.py`,挂点和缺失断言同一层(`engine/evidence.py:compose_doc` 追加违规,和 `absence_claims:3538` 并列),复用 `iter_units`、`_split_sentences` / `_SEE_TAIL`(句末依据挂到前一句)、按片段 span 涂白引文和实体的办法。
|
||||
- 报告节点 `analysis_claims`:`check`(缺省)重写一次后标出、不影响档位;`strict` 按 max_repairs 重写、仍有的进出具缺口;`off` 不核。受管级要求 `strict`(G3 加一条,旧版本照常运行、下次发布按新规则)。
|
||||
- **出口独立复核**:判断词核对进 `verify_doc`(组装和出口共用),报告文档加版本字段,只有新版本文档才核这一项——老文档复核结果不变。
|
||||
- 写作者的角色改成「挑重点、组织结构、说清变化;有分析结论时说清变化来自哪里;原因只按证据写」,写作规则加一句判断词怎么挂;`claim_priority` 的预筛词(`_DIRECTIONAL`,`engine/evidence.py:2667`)补上「主要、异常、持续、显著」等,裁判优先判这类句子。
|
||||
|
||||
### 3.6 分析范围(系统写的一段)
|
||||
|
||||
报告里只要用到了分析结论(或这次运行有分析结论),文档末尾由系统追加「分析范围」一段(写作者改不了,随文档封存,点得开):
|
||||
|
||||
- **现象**:可比性、基线、趋势结论的判定语。
|
||||
- **拆过**:每份拆解按链列出维度和判定(主要来自华东 / 分散 / 算不了的原因)。
|
||||
- **排除**:判定为分散、没有差异的那些——拆了没发现集中也是结论。
|
||||
- **没拆**:候选维度里没拆过的。候选维度确定地从目录算:拆解所用查询里的事实表上标成 attribute / status、不是标识、不遮罩、取值不多(剖析的取值数 ≤ 50 或码值表完整)的列,加上它关联的维度表;拆解用的列对不上目录时只说「候选维度核对不了」,不乱列。
|
||||
- **检验**:这次做了几次差异检验、是否已校正。
|
||||
|
||||
agent 写的 `hypothesis` 不进这一段(模型写的字不进系统渲染的正文,细案 01 §7.3),只在证据面板显示。报告节点 `analysis_scope: auto`(缺省)/ `off`。
|
||||
|
||||
### 3.7 想:分析型问数与平台方法
|
||||
|
||||
- **分析方法**(随代码升版,进评测的 prompt_fingerprint,`eval/runner.py:97-110`):
|
||||
1. 先定现象:取本期和问题对应的基期,做可比性检查;有 8 期以上历史就放回历史看——是常规波动就照实说,不硬找原因。
|
||||
2. 指标是乘积或比率时先拆因子、拆结构。
|
||||
3. 按目录里的候选维度由粗到细拆,每次给总数核对闭合;找到主要来源再下钻一层。
|
||||
4. 每次调用写明在验证什么;拆了没发现集中也是结论。
|
||||
5. 不作因果断言:数据只说明变化来自哪里;原因要有知识库原话或输入作依据,否则写成待核实的推测。
|
||||
6. 阈值、方法不由你定;算不了照实说。
|
||||
- **建图**:问题问「为什么、原因、怎么变了、哪里拖累、是否异常、正常吗、趋势、持续」时,agent 绑分析工具(问数据包装 `api/copilot.py:403-416` 加一种形状,节点手册加分析卡一段、agent 段补分析工具、搭图规则加一条)。问题意图用 `app/analysis/intent.py` 的确定词表判,传进 GraphChecker(`api/copilot_gen.py:712`),自查规则「分析类问题,agent 要绑分析工具」只挡一轮(照 coverage 的样板);`_evidence_source`(`api/copilot.py:1239`)认分析卡。
|
||||
- **复核**:新日志代码(分析算不了、判断词核对重写后仍有)登记进 `engine/review.py:WARN_CODES`,只写说明、不自动重来。
|
||||
- **内置模板 ⑪「异动分析(可追溯)」**:取数(整体周序列 + 按地区两周)→ 分析卡(基线 + 拆解)→ 报告(`analysis_claims: strict`)→ 出口(契约)。⑨ 可追溯周报不动。
|
||||
|
||||
### 3.8 评测
|
||||
|
||||
- 新期望种类(细节在 W2-b 提示词里,按 `eval/cases.py`、`gold.py`、`score.py` 的现有结构):
|
||||
- `contribution`:期望 SQL + 拆解参数 → 期望的主要来源(driver 或前 k 段)和方向。
|
||||
- `verdict`:期望 SQL + 基线 / 趋势 / 差异 / 可比性参数 → 期望的判定类(基线:常规 / 异常;趋势:上升 / 下降 / 无;差异:站得住 / 不足以下结论;可比性:可比 / 不可比)。
|
||||
- 期望值仍不许人填(`HUMAN_VALUE_KEYS` 加 segment、direction、verdict);作答前后各算一次,算子输出规范、稳定(`_fingerprint` 逐字比较)。
|
||||
- 评分沿用五种结论:答案引用了判定对得上的分析结论 → 对且可追溯;正文按说法表写对了、没引用 → 对但没引用;判定、来源对不上或答成相反 → 错;期望算不了 → 不能评分。分析结论的输入查询并进 `answer.cited`(逐题 E1)。SCORER_VERSION 加一。
|
||||
- **新的虚构库与题集**:另建 `tests/fixtures/acceptance/retail_trends.py`(数据源名 `retail_trends`,固定种子,从今天往前 26 周、截止昨天),不改现有零售库(现有测试断言了它的比例、地区排序,埋效应会改掉后面全部随机序列)。埋的效应(相对「上一个整周」):华东主导的下降(贡献)、渠道结构变化造成的退款率辛普森(结构)、订单数的常规波动(不该叫异常)、取消单激增(异常)、线上销售额持续上升(趋势)、销售额变化主要来自订单数(因子)、样本很少的门店退款率(差异不足以下结论)、本周不完整(不可比)。题集 `analysis_suite.json` 每种至少一题。
|
||||
|
||||
### 3.9 修口子:引用模式的血缘
|
||||
|
||||
引用模式的出口(`engine/nodes/io.py:209` 只调 `_check_citations`)收齐被引的指标(`[[m:]]` 片段和句末依据里的 m:),用口径卡上记的输入算 untraced:受管级的正式运行记缺口(降档),其余写进出具声明的 `untraced`、证据面板照旧标「追不到原始数据」。这样「代码节点自称取数」在受管报告里也不再能完整出具,和证据面板的说法一致。只在受管时降档:影响的现有测试只有两条受管运行的缺口列表(档位不变),见 W1-d 提示词。
|
||||
|
||||
### 3.10 设置
|
||||
|
||||
「设置 → 偏好设置 → 分析」一节(照 `pages/settings/LedgerSettings.tsx` 和 `api/settings.py` ledger 组的写法),键与缺省见细案 01 §10。发起运行时照 `_with_verify_snapshot`(`engine/launch.py:290`)写 `options["analysis"]`,只在图(含子图)里有分析卡、agent 绑了分析工具时写,别的图的 run.started 一字不变。
|
||||
|
||||
## 4. 跨块决定
|
||||
|
||||
| 编号 | 决定 | 否决的备选与代价 |
|
||||
|---|---|---|
|
||||
| D1 | 分析是平台的确定性代码,模型只选算什么 | 沙箱装 pandas 让 agent 写分析代码:算的数按设计引不了,任意代码不可复核,阈值能调到想要的结论 |
|
||||
| D2 | 算子只吃实际执行过的 SQL 快照,下钻 SQL 由 agent 写,系统用闭合从数上核对 | 改写 SQL 自动下钻:就是语义层,已明确不做;改写带关联、窗口函数的 SQL 也容易错 |
|
||||
| D3 | 新节点类型「分析卡」,不扩口径卡的函数 | 扩口径卡:口径卡编图时定死,问数据里该拆哪个维度要看了数才知道;分析产出是表和判定;会把受管口径(账本、召回)和一次性分析混在一起 |
|
||||
| D4 | 阈值只来自设置快照和分析卡上的覆盖,工具参数里没有阈值 | 让 agent 传阈值:能调出想要的结论 |
|
||||
| D5 | 判定语由系统渲染,`[[a:]]` 引用 | 让写作者照判定自己写:同一个判定十种写法,说法表也核不过来 |
|
||||
| D6 | 说法核对是确定的词表 + 绑定,不调模型 | 交给裁判:花钱、慢,只看挂了的证据;裁判仍保留,判剩下的细处 |
|
||||
| D7 | 因果词要知识库原话或输入作依据,否则写推测;拆解里点名的段按「来源」核 | 一律禁因果词:「主要由华东造成」这种记账说法太常见;一律放行:拆解被读成原因 |
|
||||
| D8 | 问数据缺省 `check`(重写一次、标出、不影响档位),受管要求 `strict`;已发布的版本照常运行 | 缺省 strict:探索运行里多出整篇重写;缺省 off:问数据里得不到这层保障 |
|
||||
| D9 | 说法核对进 verify_doc,文档加版本字段 | 只在组装时查(像缺失断言):strict 下出口不独立复核,档位凭写作节点一面之词 |
|
||||
| D10 | 分析卡的结论总能引用;agent 工具的结论在受管正式出具里和 agent 查询的格同一规矩(契约 `cells`) | 一律放行:受管报告里 agent 现场决定的分析绕过 cells 的约束 |
|
||||
| D11 | 分析结论的数不进口径账本比对,摘要不计 | 给它们新标签:前端摘要只认四种(会算出 NaN),而且它们不是口径 |
|
||||
| D12 | 平台方法挂在 ToolSpec.guide,随代码升版 | 用 Skill:库里的行、用户可改可停、seed 不更新已有库 |
|
||||
| D13 | 统计纯 Python,Wilson 从 eval/stats 移到 analysis/stats 共用;测试用预先算好的参考值钉住 | 加 scipy:几十 MB 依赖只为几个函数,本机装包慢;和评测已有的纯 Python 统计也不是一套 |
|
||||
| D14 | 新建虚构库 retail_trends 承载分析题 | 在现有零售库里埋效应:共用一条随机序列,改一处后面全变,现有断言要大改;60 天也不够 8 周基线 |
|
||||
| D15 | 引用模式的血缘缺口只在受管时降档 | 所有级别降档:会改动约十条现有测试的档位,探索运行也没必要 |
|
||||
| D16 | 分析卡的结果不作口径卡的输入 | 让口径卡读分析值:血缘要穿过分析再穿回查询,口径的等价证明、召回、双盲复算都得认一种新来源;分析结论本身已能引用 |
|
||||
| D17 | 写作目录里 A{n} 条目带整份结论(`contract.catalog_result` 读);口径卡指标的可比性记在 `comparability` 字段;「分析范围」是报告文档的结构化字段 `analysis_scope`,不进正文 | 范围段写成正文:要过裸数字和说法核对,写作者也可能改它 |
|
||||
|
||||
## 5. 分包与归属
|
||||
|
||||
集成分支 `an/w1`(cd-integ)= main `9e5debfb` + 骨架提交(`app/analysis/contract.py`、`__init__.py` 的 run / recompute 签名、`testing.py` 的假结论、设置缺省)。各包在自己的工作区从骨架拉分支;**不许 git stash**(各工作区共享同一个 stash),临时保存用 `git diff > 自己目录下的补丁`。
|
||||
|
||||
### 第 1 波(并行四包)
|
||||
|
||||
| 包 | 工作区 / 分支 | 内容 | 主要文件(归属) |
|
||||
|---|---|---|---|
|
||||
| W1-a 算子库 | cd-be / an1/a | 五个算子、统计函数、判定语、可比性(含探查)、复算;Wilson 移到 analysis/stats | `app/analysis/*`(除 contract 外全归它)、`eval/stats.py`(只改引用) |
|
||||
| W1-b 证据接入 | cd-fe / an1/b | 台账 A、写作目录、引用 a: / v:A / table:A / see:A、出处链、证据图、审计、导出 HTML、可验证报告、裁判摘录、血缘 via analysis、账本跳过 | `engine/evidence.py`(除 W1-d 的挂点)、`api/evidence.py`、`engine/judge.py`、`engine/lineage.py`、`report_export/*`、`bundle/*`、`ledger/*`、`engine/recompute.py`、`engine/sql_problems.py`;`engine/nodes/report.py` 只动 evidence_from 一处 |
|
||||
| W1-c 入口 | nr-c / an1/c | 五个分析工具与 guide、llm 里的查询容器与台账记录与方法注入、分析卡全套登记、口径卡可比性挂钩、运行对比里分析卡按项对齐、设置组与快照、使用者白名单 | `tools/*`、`engine/nodes/llm.py`、`engine/nodes/multi.py`、`engine/nodes/analysis.py`(新)、`engine/nodes/metrics.py`、`engine/schema.py`、`engine/compiler.py`、`engine/governance.py`、`engine/labels.py`、`core/events.py`、`engine/upgrade.py`、`engine/variables.py`、`engine/compare.py`、`data/catalog_impact.py`、`apps/*`、`auth/chat_policy.py`、`plain.py`、`api/settings.py`、`engine/launch.py` |
|
||||
| W1-d 说法核对 | nr-d / an1/d | 说法表与绑定、check / strict / off、出口独立复核与文档版本、写作者角色与规则、分析范围段(候选维度)、预筛词、修血缘口子、G3 一条 | `engine/analysis_claims.py`(新)、`engine/analysis_scope.py`(新)、`engine/nodes/report.py`、`engine/nodes/io.py`;在 `engine/evidence.py` 的 compose_doc / verify_doc / `_DIRECTIONAL` 只加挂点;`engine/schema.py`、`engine/governance.py`、`plain.py` 只加报告节点配置与 G3 那几行 |
|
||||
|
||||
共享文件的规矩:非归属包只在约定的挂点加几行、不重排不改名;合并冲突由编排者解。`api/copilot.py` 第 1 波谁都不动(第 2 波 W2-a 归属)。
|
||||
|
||||
### 第 2 波(并行三包,第 1 波合进集成分支后开)
|
||||
|
||||
| 包 | 工作区 / 分支 | 内容 | 主要文件 |
|
||||
|---|---|---|---|
|
||||
| W2-a 想 + 文档 | cd-be / an2/a | 分析型问数、节点手册、自查与问题意图、方法文本定稿、复核信号、内置模板 ⑪、中英文档(新增 analysis 一篇 + 七对文档 + 升级说明 + README 索引) | `api/copilot.py`、`api/copilot_gen.py`、`app/analysis/intent.py`、`engine/review.py`、`chat/*`、`seed.py`、`docs/zh-CN/*`、`docs/en/*`、`README*.md` |
|
||||
| W2-b 评测 | cd-fe / an2/b | 两种期望全链路、SCORER_VERSION、虚构库 retail_trends 与题集、评测前端 | `eval/*`、`tests/fixtures/acceptance/retail_trends.py`、`tests/fixtures/eval/analysis_suite.json`、`frontend/src/typesEval.ts`、`lib/termsEval.ts`、`pages/evals/*`、`scripts/check-evals.mjs` |
|
||||
| W2-c 前端 | nr-c / an2/c | 分析卡节点(定义、表单、卡片、配色)、证据面板分析一步、正文 a: 片段与说法违规、分析范围段、问数据时间线的分析步骤、设置「分析」一节、摘要行防 NaN、检查脚本 | `frontend/src/*`(除评测)、`scripts/check-*.mjs`(除 check-evals)、`scripts/check-all.mjs` |
|
||||
|
||||
W2-c 改了检查的项数时,把数告诉编排者,`docs/*/development.md` 由 W2-a 一处改。
|
||||
|
||||
### 复核与修复
|
||||
|
||||
每波一个复核代理(第 2 波接着用同一个,SendMessage 续上):按 a → b → c → d 试合并、跑合并后的相关测试、读改动找问题;意见用 SendMessage 交回原包代理修,不另起修复代理。
|
||||
|
||||
## 6. 验证与关口
|
||||
|
||||
- 包代理:开发中只跑相关测试文件(`-n 8`);交付前后端全量一遍;第 1 波不跑浏览器检查,第 2 波只跑自己改到的单项检查;check-all 加锁 `mkdir /tmp/agentlab-fix/checkall.lock`。跑 pytest 去掉模型相关环境变量(`env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u OPENAI_API_KEY`)。
|
||||
- 编排者在第 2 波合并后跑一次完整关口:后端全量(SQLite);本轮不加表、不改迁移的话 PostgreSQL 全量不跑(有就跑 `scripts/test-postgres.sh`);tsc;check-copy;check-docs;相关浏览器检查(evidence、report-export、bundle、chat、decode、stream、studio、tokens、evals、manage、ledger);泄露扫描(含本会话见过的真实名做指纹)。
|
||||
- 真实模型验收:用 retail_trends 题集跑评测(分析题 当前 vs 关 分析工具),人工核对几题的证据链;验收前问用户模型接入怎么配。
|
||||
- **合 main 前问用户**。
|
||||
|
||||
## 7. 风险
|
||||
|
||||
| 风险 | 应对 |
|
||||
|---|---|
|
||||
| 说法表误判(正常句子被打回) | 只收强判断词;否定、引文、系统渲染的字不扫;check 档只重写一次、不失败;评测里看重写率和标出率 |
|
||||
| agent 不用分析工具、或乱用 | 方法注入 + 自查规则 + 调用错误文案教它改;`max_calls` 上限;评测「当前 vs 关」量效果 |
|
||||
| 探查拖慢问数据 | 只在可比性检查时探、走 coverage 的总时限与 5 分钟缓存,失败退回剖析事实、再不行就「核对不了」 |
|
||||
| 大文件冲突(evidence.py 4441 行、copilot.py 2828 行) | 归属到人、挂点约定、第 1 波不碰 copilot.py |
|
||||
| 统计函数写错 | 参考值钉住(含边界:并列、n ≤ 10 精确分布、Fisher 小样本、t 分布尾部);拆解恒等式逐位测 |
|
||||
| 老报告复核结果变化 | 文档版本字段,只核新文档 |
|
||||
|
||||
## 8. 实施记录
|
||||
|
||||
### 第 1 波交付时认可的偏离(2026-10-21)
|
||||
|
||||
- W1-a:differ 三组以上每组和「其余各组合计」比(不和含它自己的整体比,不独立);整月对整月、整季对整季、整年对整年算一样长;同口径不通过只写差在哪些方面、不引 SQL 原文和字面量;新高新低按值本身判;趋势取最后连着的一段;label 消毒也用于目录叫法和当叫法用的列名;比率零分母判 zero_base;比率结果表加 n_base、n_target;乘积因子取整时按同一比例缩放;周次只认 ISO `YYYY-Www`(SQLite `%W` 不是 ISO 周);比率各段分子不超过分母时按百分点写。契约加可选字段:InputSnapshot 的 dialect / checks / no_data / mask_columns / masked_at_query,AnalysisInput 的 dialect / masked,Probe 的 expr / value。parent 按内容哈希认,入口必须原样存结论。
|
||||
- W1-c:runner 不改(已有 run_options);apps 的 lint / derive 不改(没有对应的绑定种类);compare 的配置键不登记;受管规则分工(输入不对各级报错、非 db_query 的输入画布提醒受管挡、口径卡读分析卡两级都只提示);协作成员能用分析工具但结论不进台账;口径卡的可比性结论不进台账、只挂在指标的 comparability 上(封存加载器要放行它)。
|
||||
|
||||
- W1-b:evidence_from 按「谁做的这条分析」过滤(和查询同一口径);报告文档里存的目录只留 A 条目摘要、不带整份结论(需要时用 compose / verify 收到的 catalog 或按工件取回);裁判规则原文不改,摘录里有分析结论时才追加 ANALYSIS_JUDGE_PROMPT(老判定不过期);具名标量的片段种类照数字 / 取值分,只有判定语是 analysis;可验证报告里任一输入快照只给 id 时结论也只给 id;复算的遮罩按快照里记下的查询当时的遮罩列;代入式先做可加拆解、比率拆解、波动基线三类;`see:a:A3` 宽松认;差异检验 0 次时分析范围不显示那一项。契约加 OP_LABELS / MODE_LABELS / method_label / is_result。
|
||||
|
||||
### 第 1 波复核后的决定(2026-10-21,复核意见 R1–R37)
|
||||
|
||||
- 分析卡里随数据变化的调用错误(上一层没做成、下钻的段这期没有、期次这期没有、总数格越界或为空、要比的组这期没有)不让卡失败:`analysis.run(..., refuse_data_errors=True)` 把它们记成算不了的结论,契约 REASONS 加 `parent_refused`、`input_unavailable`;agent 工具照旧交回调用错误(让它改调用);复算一律按 True 复现。结构性错误(列不存在、遮罩列、比率当可加、重复行、参数写错)照旧让卡失败。
|
||||
- 差异检验一对都拿不到 p 值(两组各 1 个样本、分母为 0)→ 算不了,REASONS 加 `untestable`。
|
||||
- 单份快照按期次分组的拆解也核本期完不完整:不完整算不了(partial_target),核对不了附说明。
|
||||
- 周次:`YYYY-Www` 不再一律按 ISO 算;按 SQL 认出期次列的算法(SQLite strftime %W / %U、MySQL DATE_FORMAT %U / %u、to_char WW / IW),能算真实起止就算,算不了就起止置空、判「核对不了」,绝不判完整;W00 / W53 不走 ISO。
|
||||
- `_classify` 的结论句判定回到原来的词表,新增的判断词只用于裁判的预筛排序(不改已发布版本的档位)。
|
||||
- 说法表按复核第 4 节调整(静态构成、建议计划预测、业务上的「异常」名词、「来源于」、「表结构」、「相当」不再误报;补高频漏报写法);还没有线上文档,不升 LEXICON_VERSION。表格正文的格不核。
|
||||
- 写作者提示词在没有分析的图里也变(新 ROLE + 「没有分析结论就不下这类判断」):照 D8 保留,这是本轮要的效果;升级说明写清。
|
||||
- 候选维度只认码值表(剖析目前没有每列取值数)、模板 ⑨ 补 analysis_claims strict:记为偏离,认可。
|
||||
|
||||
### 合并时要统一的
|
||||
|
||||
- 算子的叫法有三份(契约 OP_LABELS / MODE_LABELS、engine/labels.py 的 ANALYSIS_OP_LABEL / ANALYSIS_MODE_LABEL、phrases.py 的「没有做成」那句)→ 只留契约一份。
|
||||
- tests/bundle_samples.py 补一页带分析结论的样本(第 2 波 check-bundle、check-report-export 要覆盖)。
|
||||
|
||||
### 第 2 波要带上的事
|
||||
|
||||
- W2-a:review 的 WARN_CODES 登记 analysis_refused、metric_comparability_skipped(以及 W1-b / W1-d 新增的日志代码);方法 guide 定稿时升 id 里的版本号;方法文本写明周序列的期次用每周第一天的日期或 ISO `YYYY-Www`;助手的工具清单从第 1 波起已经列出五个分析工具;`_evidence_source`(`api/copilot.py:1251`)认分析卡。
|
||||
- W2-b:评测指纹排除 `probes[*].at`(现查时刻)。
|
||||
- W2-c:节点叫法「分析卡」、字段叫法「分析项」「阈值覆盖」、方法与模式的叫法在 engine/labels.py(ANALYSIS_OP_LABEL / ANALYSIS_MODE_LABEL);新事件 analysis.end;tool.error 新字段 call_error;运行对比新字段 analyses;设置组 analysis。
|
||||
|
||||
### 第 2 波交付时的决定(2026-10-21)
|
||||
|
||||
- W2-b:期望指纹不比 inputs[*].artifact(查询快照记着 elapsed_ms,同一份数据每次查出来工件都不同);期望 SQL 只返回两期时可以不写基期、本期;算期望的「今天」用服务端当天;编辑器保留多个期望(以前会丢第一个以外的)。说法表不加「可比 / 不可比」一类(不打回谨慎的提醒),评分另用一张小词表认正文里「两期不能直接比」的说法。评测变体加「分析工具」开 / 关和「分析工具贡献」预设(真实模型验收用它量效果)。
|
||||
- W2-a:自查只在问数据里、只针对查库却没绑分析工具的 agent;分析调用写错后又做成了不再报、一直没改对的记 analysis_call_failed(只写说明,不让整轮重来);模板 ⑪ 的 SQL 只按 SQLite 写;文档里内置工具 23 个、模板 11 个、节点类型 19 种。关分析工具时节点手册连分析卡一整条一起去掉(对照才干净)。
|
||||
|
||||
### 第 2 波复核要带上的
|
||||
|
||||
- `[[table:An cols=…,share]]` 里占比按原始小数渲染(1.0133380758),不是百分数:结果表要带每列的显示格式(占比、变化率、权重按百分数),证据渲染照它。
|
||||
- analysis_trend 的工具说明开头写「趋势:」,契约叫法是「趋势判断」。
|
||||
- termsEval(W2-b)里算子与模式的叫法一份,W2-c 若在 lib/terms.ts 另建一份要统一成一份。
|
||||
- 新 code 前端要认:analysis_call_failed、analysis_tools_missing、analysis_tools_off。
|
||||
- development.md / README 的前端检查项数等 W2-c 交数后改;评测文档和 an2/b 最终代码核一遍。
|
||||
@@ -0,0 +1,303 @@
|
||||
# 细案 01:分析算子、判定与说法表
|
||||
|
||||
> 总方案见 00-总方案.md,冲突以总方案为准。本篇定「算什么、怎么算、怎么判、怎么说」:五个算子的输入、方法、判定、算不了的情形,统一的结果形状,判定语模板,说法表与绑定规则,设置缺省值。例子一律用虚构零售库(地区:华东、华南、华北、西南;渠道:线上、线下)。
|
||||
|
||||
## 1. 统一的结果形状:分析结论
|
||||
|
||||
一次分析(agent 调一次分析工具,或分析卡里的一项)产出一份**分析结论**,内容寻址存成工件(kind `analysis_result`),在证据台账里记一条 kind `analysis`,写作目录编号 A1、A2……(和 Q、K 同一套编号规则,按台账先后)。
|
||||
|
||||
```
|
||||
{
|
||||
"op": "decompose" | "baseline" | "trend" | "differ" | "comparable",
|
||||
"mode": "additive" | "ratio" | "factor" | "rate" | "mean" | null, # 只有 decompose、differ 有
|
||||
"method": "decompose.additive@1", # 方法 + 版本;改算法就升版本号
|
||||
"params": {...}, # 规范化后的调用参数(列名、期次、维度、标签……)
|
||||
"settings": {...}, # 用到的阈值(发起时的快照 + 分析卡上写的覆盖)
|
||||
"inputs": [ # 输入:都是本次运行里交回过的查询快照
|
||||
{"ref": "Q3", "artifact": "<sha256>", "columns": [...], "rows": "all" | [i, j, ...]},
|
||||
{"ref": "Q1.r0.gmv", "artifact": "<sha256>", "value": "1234.5", "role": "headline_target"}
|
||||
],
|
||||
"probes": [...], # 可比性检查现查的表范围(列、最小、最大、来源:现查 / 剖析 / 取值观察、时刻)
|
||||
"status": "ok" | "refused",
|
||||
"reason_code": null | "truncated" | "history_short" | ..., # 见 §8
|
||||
"reason": null | "(中文,一种说法)",
|
||||
"table": {"columns": [...], "labels": {...}, "rows": [[...]]}, # 结果表,形状同查询快照,[[v:]] / [[table:]] 能引
|
||||
"values": {"total_delta": "...", "top_share": "...", ...}, # 具名标量,[[a:A3.top_share]] 能引
|
||||
"verdict": {"code": "driver", "subjects": [["华东"]], "direction": "down"} | null,
|
||||
"criterion": "(判定标准的中文,一句)",
|
||||
"phrase": "(判定语,由系统按模板渲染,§7)",
|
||||
"caveats": [{"code": "offset", "text": "..."}],
|
||||
"hypothesis": "(agent 写的这次在验证什么,只在证据面板显示,§9.3)"
|
||||
}
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
- **纯函数**:结论只由 inputs(快照里的格)、probes、params、settings、method 决定;证据面板、导出、可验证报告用同一个函数复算,复算结果和封存的逐字段相同才算核对通过。方法升版后复算按当前版本算,不同就照实写「运行时用的是 v1,现在是 v2,复算结果不同」。
|
||||
- **数用十进制**:decompose 全程 `Decimal`(同 engine/compare.py 的做法),各段之和逐位等于总变化;统计量(z、p、斜率)用浮点,渲染按 cell_format 的规则。
|
||||
- **只读快照、不发查询**:算子本身不查库。唯一的例外是可比性检查要现查表的日期范围(§6),走 data/coverage 现成的探查(只读守卫、遮罩列不探、总时限、5 分钟缓存、失败退回剖析事实),探查结果作为 probes 记进结论,复算用记下的值。
|
||||
- **遮罩**:遮罩列(数据源 mask_columns,以及按 SQL 认出改了名字的遮罩列,同 compare.py `_hidden`)不能当维度、不能当度量;拿它们调用是调用错误(§8.1),结论里绝不出现遮罩值。
|
||||
- **截断的快照不算**:任一输入快照 `truncated` → 算不了(reason_code `truncated`),原因写「Q3 只取回了前 1000 行,各段之和不是完整的和」。
|
||||
- **行要唯一**:同一维度键、同一期次只能有一行(还有别的列在拆行就是 SQL 没按这些维度汇总)。重复 → 调用错误,提示「在 SQL 里按 地区、周 汇总」。不在算子里替人求和:存量跨天相加这类错误只有 SQL 那边知道。
|
||||
- **空值**:度量格为空按「这一段这一期没有值」处理:decompose 记为 0 并在 caveats 写明哪几段为空;统计类算子跳过这一期,跳过后历史不够的照算不了处理。
|
||||
|
||||
## 2. 变化拆解(decompose)
|
||||
|
||||
回答「变化从哪来」。三种模式,agent 按指标的性质选,算子核对选得对不对。
|
||||
|
||||
### 2.1 可加(additive)——按维度算贡献
|
||||
|
||||
**输入**
|
||||
|
||||
- 一份快照,含维度列 `by`(1–2 列)、期次列 `period`、度量列 `measure`,`base`、`target` 是期次列里的两个值;或者两份快照(`base_query`、`target_query`),各自只有维度列和度量列,此时先做可比性检查(§6),不可比的照样算、判定后附上可比性结论。
|
||||
- 可选 `headline`:基期、本期总数各一格(如 `Q1.r1.gmv`、`Q1.r0.gmv`),用来核对**拆解闭合**。
|
||||
- 可选 `parent`:上一层拆解的结论和那一段(如 `{"of": "A3", "key": ["华东"]}`),用来下钻:这一层各段之和要等于 A3 里华东那一段的基期、本期值。
|
||||
- 目录里度量列标成 ratio(比率)的 → 调用错误:「比率不能按段相加,改用 ratio 模式,给分子、分母两列」。标成 identifier / status / attribute 的 → 调用错误。没标的照算,caveats 写「目录没标这一列的度量类型」。
|
||||
|
||||
**计算**
|
||||
|
||||
- 每段 `base_i`、`target_i`(缺的一边记 0,标「新出现 / 消失」),`delta_i = target_i − base_i`,`pct_i = delta_i / base_i`(base 为 0 不给)。
|
||||
- 总数 `B = Σ base_i`、`T = Σ target_i`、`Δ = T − B`。
|
||||
- 闭合:给了 headline / parent 时,`B`、`T` 要分别等于它们(按十进制精确相等;headline 是取整过的,按它的书写精度容差,同 engine/tolerance)。不闭合 → 照算各段变化,但**不给占比、不下集中类判定**(verdict 为 `unclosed`),caveats 写差多少、可能的原因(有段没取全、两边筛选不同、关联重复计数)。没给 headline 时以各段之和为总数,criterion 写明「以各段之和为总数」。
|
||||
- 占比 `share_i = delta_i / Δ`(Δ 为 0 不给)。抵消:和 Δ 方向相反的段的变化绝对值之和 `G_opp`。
|
||||
|
||||
**判定**(阈值见 §10)
|
||||
|
||||
| verdict | 条件 | subjects |
|
||||
|---|---|---|
|
||||
| `flat` | `|Δ| / |B| < flat_pct` | 无;有抵消时附抵消 |
|
||||
| `driver` | 最大的 `share_i ≥ main_share` | 那一段 |
|
||||
| `concentrated` | 不满足 driver;最小的 k 使前 k 段(按 share 降序)之和 `≥ concentration`,且 `2 ≤ k ≤ max(2, ⌈0.2·段数⌉)` | 前 k 段 |
|
||||
| `dispersed` | 其余 | 无 |
|
||||
| `unclosed` | 闭合核对没过 | 无 |
|
||||
|
||||
- `G_opp ≥ offset_ratio · |Δ|` 时加 caveat `offset`:「下降的段合计 −120 万,上升的段合计 +40 万,互相抵消了一部分」。有抵消时 share 可以超过 100%(华东 −120、总共 −80,华东占 150%),判定照常,判定语会说清。
|
||||
- 段数少于 2 → 算不了(`too_few_segments`)。
|
||||
- 结果表:维度列 + `base`、`target`、`delta`、`pct`、`share`、`flag`(新出现 / 消失 / 为空),按 `|delta|` 降序;全部段都在工件里,写作目录只给前 `table_top_k` 段和「其余 n 段合计」。
|
||||
- values:`base_total`、`target_total`、`delta_total`、`pct_total`、`top_key`、`top_share`、`top_k`、`top_k_share`、`gross_up`、`gross_down`、`segments`。
|
||||
|
||||
### 2.2 比率(ratio)——拆成结构变化和各段自身变化
|
||||
|
||||
**输入**:维度列、期次列、分子列 `numerator`、分母列 `denominator`(如退款单数 / 订单数、销售额 / 订单数);可选 headline(整体比率的两格)。
|
||||
|
||||
**计算**(中点对称拆法,精确可加)
|
||||
|
||||
- 各段权重 `w_i = D_i / ΣD`,比率 `r_i = N_i / D_i`;整体 `R = ΣN / ΣD`,`ΔR = R' − R`。
|
||||
- 结构效应 `mix_i = (w_i' − w_i) · (r̄_i − R̄)`,自身效应 `rate_i = (r_i' − r_i) · w̄_i`,其中 `r̄_i = (r_i + r_i')/2`、`w̄_i = (w_i + w_i')/2`、`R̄ = (R + R')/2`。
|
||||
- 恒等式 `Σmix_i + Σrate_i = ΔR`(因为 `Σ(w_i' − w_i) = 0`);单测钉住逐位相等。减去 `R̄` 是为了让单段的结构效应读得懂:一段占比变大,只有它的比率低于平均时才拉低整体。
|
||||
- 一边分母为 0 的段:那一边权重 0、比率取另一边的(自身效应为 0,变化全记在结构上),表里标出;两边都为 0 的段剔除并写明。
|
||||
- headline 闭合:整体比率要等于 ΣN/ΣD(按 headline 的书写精度容差)。
|
||||
|
||||
**判定**
|
||||
|
||||
| verdict | 条件 |
|
||||
|---|---|
|
||||
| `flat` | `|ΔR| / |R| < flat_pct` |
|
||||
| `mix_driven` | `Σmix / ΔR ≥ main_share` 且 `Σrate / ΔR < main_share` |
|
||||
| `rate_driven` | `Σrate / ΔR ≥ main_share` 且 `Σmix / ΔR < main_share` |
|
||||
| `both` | 其余 |
|
||||
|
||||
- **辛普森**:分母两期都不小于 `min_denominator` 的段里,按 `w̄` 加权有 `≥ 0.8` 的段比率变化方向和 ΔR 相反 → caveat `simpson`,判定语写「各段的退款率大多在下降,整体却上升:变化来自结构,退款率高的段占比从 x 升到 y」。
|
||||
- subjects:`rate_driven` 取自身效应最大(和 ΔR 同向)的段,`mix_driven` 取结构效应最大的段。
|
||||
- 分母小于 `min_denominator` 的段在表里标「分母小」,不参与辛普森的多数判断。
|
||||
- 结果表:维度列 + `d_base`、`d_target`、`w_base`、`w_target`、`r_base`、`r_target`、`mix`、`rate`、`total`、`flag`。values:`r_base_total`、`r_target_total`、`delta`、`mix_total`、`rate_total`、`mix_share`、`rate_share`。
|
||||
|
||||
### 2.3 乘积(factor)——拆成因子
|
||||
|
||||
**输入**:期次列(或两行),乘积列 `product`(销售额),因子列 `factors`(订单数、客单价;2–4 个)。
|
||||
|
||||
- 闭合:每期 `product ≈ Π factors`,相对误差不超过 `max(1e-6, Σ 因子按书写精度的半个末位 / 因子值)`;不闭合 → 调用错误「这几列相乘不等于销售额(差 0.8%),不是乘积关系」。
|
||||
- 任一值 ≤ 0 → 算不了(`non_positive`):对数拆解要求全为正。
|
||||
- 方法 LMDI-I:`contrib_k = L(M', M) · ln(F_k' / F_k)`,`L(a, b) = (a − b) / (ln a − ln b)`,`L(a, a) = a`;`Σcontrib_k = M' − M`。
|
||||
- 判定:`flat` / `driver`(某因子 `contrib_k / ΔM ≥ main_share`,subject 是因子名)/ `both`。
|
||||
- 结果表:`factor`、`base`、`target`、`pct`、`contrib`、`share`。不按维度拆:要「哪个地区的客单价」就先 factor 再对客单价做 ratio。
|
||||
|
||||
### 2.4 下钻
|
||||
|
||||
`parent` 把几层拆解连成一条链:A5(华东按省份)是 A3(按地区)里华东那一段的拆解。闭合按 parent 那一段的值核对,链深度不超过 `max_drill_depth`(超了是调用错误)。证据面板按链显示;分析范围(细案 00 §6)按链列「拆过」。
|
||||
|
||||
## 3. 波动基线(baseline)
|
||||
|
||||
回答「这个变化大不大、算不算异常」:把本期放回它自己的历史里看。
|
||||
|
||||
**输入**:一份快照,期次列 `period` + 度量列 `measure`(一条序列;要看某一段就在 SQL 里筛好);可选 `target`(缺省最后一期)、`basis`(`change` 缺省:和上一期比的变化率;`level`:值本身,给存量、比率用)、`grain`(day / week / month / quarter,缺省按期次值推断)、`lag`(缺省 day→7,即和上周同一天比,避开星期效应;week→1;month→1;要同比就写 52 / 12,历史要相应够长)、`label`(度量的叫法,§7.3 消毒)。
|
||||
|
||||
**前提**(不满足就算不了,原因照实写)
|
||||
|
||||
- 期次认得出、能排序(日期、`YYYY-MM`、`YYYY-Www`、整数序号):认不出 → `period_unreadable`。
|
||||
- 本期完整:用 §6 的完整性检查;本期没过完或数据没到 → `partial_target`(「本周数据只到 10 月 16 日,还差 3 天,和完整的周比没有意义」)。
|
||||
- 期次连续:相邻两期中间缺期的,那一对不算变化;本期和它的比较期之间缺期 → `target_gap`。
|
||||
- 历史够长:有效的历史变化(或值)不少于 `min_history` → 否则 `history_short`(「只有 5 期历史,至少要 8 期」);最多用 `max_history` 期。
|
||||
- 比较期为 0 不能算变化率 → `zero_base`。
|
||||
|
||||
**计算**:历史的中位数 `m`、中位绝对偏差 `MAD`,`σ̂ = 1.4826·MAD`;稳健 z = `(x − m)/σ̂`;常规波动范围 `[m − k_warn·σ̂, m + k_warn·σ̂]`;本期在「历史 + 本期」里的名次;历史最小、最大值。`σ̂ = 0`(历史每期都一样)时:本期也一样判 `within_band`,不一样判 `far_outside_band`,判定语改说「过去 N 期每期都是 x」。
|
||||
|
||||
**判定**
|
||||
|
||||
| verdict | 条件 |
|
||||
|---|---|
|
||||
| `within_band` | `|z| < k_warn` |
|
||||
| `outside_band` | `k_warn ≤ |z| < k_alert` |
|
||||
| `far_outside_band` | `|z| ≥ k_alert` |
|
||||
|
||||
direction 取 z 的正负;本期是「历史 + 本期」里的最大 / 最小值时加 caveat `record_high` / `record_low`(说法表里「历史新高 / 新低」要它)。values:`x`、`median`、`band_lo`、`band_hi`、`z`、`rank`、`n_history`、`hist_min`、`hist_max`。
|
||||
|
||||
为什么用中位数和 MAD、不用均值和标准差:业务序列常有促销周这类极端值,均值和标准差会被它拉宽,正常的周都显得「不异常」,异常的周也显得不异常。
|
||||
|
||||
## 4. 趋势(trend)
|
||||
|
||||
回答「是持续在变,还是一次波动」。
|
||||
|
||||
**输入**:同 baseline 的序列(期次列 + 度量列),取最后 `n` 期(`trend_min_points ≤ n ≤ max_history + 1`)。前提:期次认得出、连续(中间缺期 → `series_gap`),最后一期完整(同 §3)。
|
||||
|
||||
**计算**
|
||||
|
||||
- Theil–Sen 斜率:所有两两斜率的中位数;相对斜率 = 斜率 / 序列中位数(中位数为 0 只给绝对值)。
|
||||
- Mann–Kendall:`S = Σ_{i<j} sgn(y_j − y_i)`;无并列且 n ≤ 10 用精确分布(Kendall 统计量的分布用递推算出,不查表),否则正态近似(并列修正方差、连续性校正),双侧 p。
|
||||
- 末尾连续同向:从最后一期往前数,相邻变化同号的期数(变化为 0 断开)。
|
||||
|
||||
**判定**:`p < trend_alpha` 且斜率 > 0 → `rising`;< 0 → `falling`;否则 `no_trend`。values:`slope`、`rel_slope`、`p`、`n`、`run_length`、`run_direction`。日粒度序列加 caveat `weekday_effect`(「日数据有星期效应,看趋势建议按周汇总」)。
|
||||
|
||||
已知局限照实写进方法说明:Mann–Kendall 假设各期独立,业务序列常有自相关,p 会偏小;所以缺省 n 至少 6、α 取 0.05,判定语只说「呈上升趋势」,不说「显著上升」。
|
||||
|
||||
## 5. 差异检验(differ)
|
||||
|
||||
回答「这两组(或两期)真的不一样,还是样本波动」。
|
||||
|
||||
**输入**
|
||||
|
||||
- `rate` 模式:成功数列 + 试验数列(转化单数 / 访客数),按维度列 `by` 分组;`reference` 指定对照组(缺省整体),或 `pairs` 指定要比的几对;也可以按期次比同一组的两期。
|
||||
- `mean` 模式:每组的均值、标准差、样本数三列,或者合计、平方和、样本数三列(SQLite 没有标准差函数,`SUM(x)`、`SUM(x*x)`、`COUNT(*)` 都能写)。
|
||||
- `rows` 模式:逐行的值列 + 分组列(快照不超过 1000 行且没截断),算子自己算均值、方差,另做敏感性。
|
||||
|
||||
**计算**
|
||||
|
||||
- 比率:每组 Wilson 区间(和评测用同一个函数,从 eval/stats 移到 analysis/stats,评测改为引用);两组之差用 Newcombe 区间;p 值:最小期望频数 ≥ `min_expected` 用合并比例的 z 检验,否则用 Fisher 精确检验(超几何概率用 `math.lgamma` 累加)。
|
||||
- 均值:Welch t 检验,自由度按 Welch–Satterthwaite;t 分布的分布函数用正则化不完全 β 函数(连分式),分位数用二分求逆。
|
||||
- 一次调用里比了多对:按 Holm 校正,表里同时给原始 p 和校正后的 p,caveat `multiple_comparisons`(「比了 4 对,已按次数校正」)。整个运行里做了几次检验由分析范围统计(细案 00 §6),不回头改已封存的结论。
|
||||
- `rows` 模式的敏感性:去掉离均值最远的那一个值后重算,判定变了 → caveat `outlier_sensitive`(「去掉最大的一笔后,差异不再站得住」)。
|
||||
|
||||
**判定**:校正后 `p < differ_alpha` → `differs`(direction 按差的正负);否则 `no_evidence`。任一组样本数小于 `min_n`(均值)或用了 Fisher(比率)→ caveat `small_sample`。
|
||||
|
||||
判定语不出现「p 值」「显著性」这类术语:`differs` 说「差异站得住」,`no_evidence` 说「差异可能只是样本波动,样本量:A 230、B 40」;p 值、区间在表和证据面板里。
|
||||
|
||||
## 6. 可比性检查(comparable)
|
||||
|
||||
回答「这两期能不能直接比」。三处用到:agent 单独调用;decompose 两份快照、baseline / trend 的本期完整性;口径卡里跨两份查询算的环比、同比(细案 00 §4.3)。
|
||||
|
||||
**检查项**(每项 pass / warn / fail / unknown,unknown 只写「核对不了」,不判不可比)
|
||||
|
||||
| 项 | 怎么判 | fail / warn |
|
||||
|---|---|---|
|
||||
| 同口径 | 两边 SQL 用口径账本的 `explain_sql_diff` 比:完全相同 / 只差字面量 / 结构不同 | 结构不同 fail(写出差在哪);只差字面量时,非日期的字面量也不同(`'华东'` 对 `'华南'`)→ 比的是两段不是两期,fail「两边除了日期,筛选的还不一样」;同一份快照里按期次分组的天然同口径 |
|
||||
| 窗口长度 | 用 data/coverage 的 `filters` 取业务日期列(目录 business_date,没有就取时间谓词列)上的区间,现算的界照 coverage 在库里算;算两边天数 | 不相等:度量是 flow(可加流量)fail,ratio / stock / 没标 warn |
|
||||
| 整期 | 窗口终点和表里这一列的实际最大值、运行当天比(实际范围用 coverage 的现查 + 剖析兜底,记进 probes) | 窗口没过完或数据没到:flow fail(「本期只有 3 天数据」),其余 warn |
|
||||
| 星期构成 | 日粒度、天数不是 7 的倍数时,数两边的周六、周日天数 | 不同 warn(「两段的周末天数不同:4 天对 6 天」) |
|
||||
| 数据问题 | 两边查询结果上的 SQL 检查错误、「查询区间里没有数据」 | 没有数据 fail,SQL 检查错误 warn |
|
||||
|
||||
**判定**:全部 pass / unknown → `comparable`;有 warn 没有 fail → `conditional`;有 fail → `incomparable`。判定语列出 fail、warn 的原因,一句一个。
|
||||
|
||||
## 7. 判定语
|
||||
|
||||
### 7.1 由系统渲染
|
||||
|
||||
`[[a:A3]]` 渲染成 A3 的判定语,`[[a:A3.top_share|pct]]` 渲染具名标量(换算后缀同 `[[m:]]`)。判定语里的数照 cell_format 渲染、点得开 A3 的出处链。写作者不写判定,只引用判定——这是「叙述层无算术」往前走的一步:分析判定和数字一样由系统写。
|
||||
|
||||
### 7.2 模板(一种说法,analysis/phrases.py 一处定义,前后端都从结论里读渲染好的字符串)
|
||||
|
||||
| op / verdict | 判定语 |
|
||||
|---|---|
|
||||
| decompose additive `driver` | `{label}{变化},主要来自{subject}({subject 的变化},占{share})` |
|
||||
| `concentrated` | `{label}{变化},集中在{subjects}(合计占{top_k_share})` |
|
||||
| `dispersed` | `{label}{变化},分散在各{维度名},没有哪一段占到一半` |
|
||||
| `flat` | `{label}基本持平({pct})`;有抵消时接「,内部此消彼长:{最大的上升段} {变化}、{最大的下降段} {变化}」 |
|
||||
| `unclosed` | `按{维度名}拆开后各段之和和总数对不上(差 {gap}),不判断变化来自哪里` |
|
||||
| ratio `mix_driven` | `{label}{变化},主要来自结构变化:{subject}占比从 {w} 到 {w'}` |
|
||||
| `rate_driven` | `{label}{变化},主要来自各段自身的变化,{subject}影响最大` |
|
||||
| `both` | `{label}{变化},结构变化和各段自身变化都有影响(各占 {mix_share}、{rate_share})` |
|
||||
| factor `driver` | `{label}{变化},主要来自{factor}的变化(贡献 {contrib},占{share})` |
|
||||
| baseline `within_band` | `{label}{本期变化},在过去 {n} {期}的常规波动范围内({lo} 至 {hi})` |
|
||||
| `outside_band` | `{label}{本期变化},超出过去 {n} {期}的常规波动范围({lo} 至 {hi})` |
|
||||
| `far_outside_band` | `{label}{本期变化},明显超出过去 {n} {期}的常规波动范围({lo} 至 {hi})` |
|
||||
| trend `rising` / `falling` | `过去 {n} {期}{label}呈上升 / 下降趋势(每{期}约 {rel_slope})`;`run_length ≥ 3` 时接「,已连续 {run} {期}上升 / 下降」 |
|
||||
| `no_trend` | `过去 {n} {期}{label}没有明显的上升或下降趋势` |
|
||||
| differ `differs` | `{A}的{label}({a}){高于 / 低于}{B}({b}),差异站得住` |
|
||||
| `no_evidence` | `{A}和{B}的{label}差异可能只是样本波动(样本量 {nA}、{nB})` |
|
||||
| comparable | `两期可比` / `两期有条件可比:{原因}` / `两期不可比:{原因}` |
|
||||
| 算不了 | `{op 的叫法}没有做成:{reason}` |
|
||||
|
||||
caveats 渲染在判定语后面,用「;」接,最多两条,其余在证据面板。
|
||||
|
||||
### 7.3 系统渲染的字里不能夹带模型写的数
|
||||
|
||||
判定语里的 `label`(度量叫法)、维度值、因子名是 agent 或数据给的。数据里的维度值照原样(遮罩列不当维度,已排除)。agent 给的 `label` 消毒:去掉数字、百分号、单位符号、引用标记,长度不超过 20 字,消毒后为空就用列名。否则模型可以把「销售额(同比 +30%)」塞进 label,借系统渲染绕过裸数字检测。`hypothesis` 不进任何系统渲染的正文(只在证据面板,标「agent 写的假设」)。
|
||||
|
||||
## 8. 算不了与调用错误
|
||||
|
||||
### 8.1 调用错误(不记结论,像 SQL 写错一样把错误交回 agent 改)
|
||||
|
||||
列不存在、列被遮罩、度量列不是数、角色和目录度量类型冲突(比率当可加)、同一键同一期多行、`base` / `target` 不在期次列里、乘积不闭合、`parent` 指向的结论不存在或不是 decompose、下钻超过深度、本运行分析次数用完(`max_calls`)。错误文案一种说法,告诉 agent 怎么改。
|
||||
|
||||
### 8.2 算不了(记成结论,status `refused`)
|
||||
|
||||
reason_code:`truncated`、`too_few_segments`、`history_short`、`partial_target`、`target_gap`、`series_gap`、`period_unreadable`、`zero_base`、`non_positive`、`incomparable_sides`(decompose 两份快照的口径结构不同,不拆)。「算不了」本身就是结论:写作者可以照实写「历史只有 5 周,判断不了是否异常」,说法表里的「异常」类判断不能挂一个 refused 的结论。
|
||||
|
||||
## 9. 说法表与绑定规则
|
||||
|
||||
### 9.1 判断词的类
|
||||
|
||||
| 类 | 判断词(举例,analysis/claims.py 一处定义,带版本) | 要挂的分析 | 判定要对得上 |
|
||||
|---|---|---|---|
|
||||
| 来源 | 主要来自、主要由、主要是…(下降 / 增长)、大部分来自、绝大部分、集中在、主导、拖累、拉动、带动、贡献最大 | decompose | `driver` / `concentrated`;句子里点名的段要在 subjects 里;拖累要那一段变化为负、拉动 / 带动为正 |
|
||||
| 分散 | 分散、普遍、全面(上升 / 下降)、各…都 | decompose | `dispersed` |
|
||||
| 抵消 | 抵消、此消彼长、一增一减 | decompose | 有 `offset` caveat 或 `flat` 带抵消 |
|
||||
| 结构 | 结构变化、结构性、占比变化带来 | decompose ratio | `mix_driven` / `both` |
|
||||
| 异常 | 异常、反常、罕见、明显偏离、超出正常、大幅、骤降、暴跌、激增、飙升、剧烈 | baseline | `outside_band` / `far_outside_band`;方向对得上 |
|
||||
| 新高新低 | 历史新高、历史新低、创新高、创新低、前所未有 | baseline | 对应的 `record_high` / `record_low` |
|
||||
| 正常 | 正常波动、常规波动、正常范围、并不异常 | baseline | `within_band` |
|
||||
| 趋势 | 趋势、持续(上升 / 下降)、连续…(周 / 月)、一路、逐步、节节、稳步 | trend | `rising` / `falling`,方向对得上;「连续」要 `run_length ≥ 3` 且方向一致 |
|
||||
| 无趋势 | 没有明显趋势、基本平稳、趋势不明显 | trend | `no_trend` |
|
||||
| 差异 | 显著高于 / 低于、明显高于 / 低于、确实更高 / 更低、差异明显 | differ | `differs`,方向对得上 |
|
||||
| 无差异 | 差异不大、差别不大、没有明显差别、相当 | differ | `no_evidence` |
|
||||
| 因果 | 因为、由于、导致、造成、引起、受…影响、归因于、原因是、源于、所致、得益于 | 知识库原话 `[[q:]]` 或运行输入 `[[i:]]` 在同一句;或用了推测说法(可能、或许、推测、待核实、不排除、疑似) | — |
|
||||
|
||||
- **否定**:判断词前 4 个字以内有「不、没有、没、并非、并不、未、无」的翻到对应的反面类(「并不异常」→ 正常,「没有明显趋势」→ 无趋势;「并非主要来自华东」→ 要 decompose 且华东不在 subjects 里)。
|
||||
- **来源和因果的分界**:句子挂了 decompose,因果词前后点名的是这份结论的段或因子(「下降主要由华东造成」)→ 按来源核,这是记账意义上的「来自」;点名的不是(「由于促销结束导致下降」)→ 按因果核。拆解只能说明变化来自哪里,说明不了为什么。
|
||||
- **不扫的地方**:知识库原话(`[[q:]]` 的原文整段涂白,同裸数字)、系统渲染的判定语与分析范围块、标题行。
|
||||
|
||||
### 9.2 怎么挂
|
||||
|
||||
一句话的分析依据 = 这句里出现的 `[[a:An…]]`、`[[v:An.…]]`、`[[table:An …]]`,以及句末 `[[see:An]]`(和 `[[see:Q1]]` 同一种写法)。来源、异常这些类要的 op 必须在这句的依据里出现;有好几个时任一个对得上就算对。
|
||||
|
||||
### 9.3 违规与处置
|
||||
|
||||
| 代码 | 什么时候 | 说法(给写作者的,给人看的另有一句) |
|
||||
|---|---|---|
|
||||
| `analysis_claim_uncited` | 句子有判断词,依据里没有对应种类的分析结论 | 「『主要来自』要挂按维度拆解的结论([[see:A3]]);没有拆解就只写各段的变化,不下『主要』的判断」 |
|
||||
| `analysis_claim_mismatch` | 挂了,但判定、点名的段、方向对不上(含挂了算不了的结论) | 「A3 判的是变化分散在各地区,没有哪一段占到一半,不能写『主要来自华东』」 |
|
||||
| `causal_unsupported` | 因果词没有知识库原话或输入作依据,也没用推测说法 | 「『由于促销结束』没有依据:数据只能说明变化来自哪里;要写原因,引用知识库原话,或写成『可能与…有关,待核实』」 |
|
||||
|
||||
报告节点 `analysis_claims`:
|
||||
|
||||
- `check`(缺省,含问数据):违规交回写作者重写**一次**(同 inline_see、absence_claim 那一类,不按 max_repairs 反复),仍有的标在报告里(证据面板、审计、导出都看得到),不让节点失败、不影响出具档位。
|
||||
- `strict`:按 `max_repairs` 重写;仍有的记成出具缺口,带出具契约的降档;受管级别要求 `strict`(门禁 G3 加一条)。
|
||||
- `off`:不核。
|
||||
|
||||
## 10. 设置缺省值(设置 → 偏好设置 → 分析;发起时快照进 run.options["analysis"])
|
||||
|
||||
| 键 | 缺省 | 用在 |
|
||||
|---|---|---|
|
||||
| `main_share` | 0.5 | 「主要」:一段(一个因子、一种效应)占总变化的比重 |
|
||||
| `concentration` | 0.8 | 「集中」:前 k 段合计占比 |
|
||||
| `offset_ratio` | 0.25 | 反向段合计超过总变化的这个比例记抵消 |
|
||||
| `flat_pct` | 0.005 | 总变化小于基期的 0.5% 算基本持平 |
|
||||
| `k_warn` / `k_alert` | 2 / 3 | 波动基线的稳健 z |
|
||||
| `min_history` / `max_history` | 8 / 52 | 基线、趋势用的历史期数 |
|
||||
| `trend_min_points` / `trend_alpha` | 6 / 0.05 | 趋势 |
|
||||
| `differ_alpha` / `min_n` / `min_expected` | 0.05 / 30 / 5 | 差异检验 |
|
||||
| `min_denominator` | 30 | 比率拆解里「分母小」 |
|
||||
| `max_calls` / `max_drill_depth` | 12 / 3 | 一次 agent 运行最多分析几次、下钻几层 |
|
||||
| `table_top_k` | 10 | 写作目录、判定语里列几段 |
|
||||
|
||||
- **agent 改不了阈值**:分析工具的参数里没有阈值,阈值只来自设置快照;分析卡(模板)可以在节点上写覆盖,写进图、随版本固定。这样模型不能把阈值调到想要的结论。
|
||||
- 每份结论记下实际用的阈值,判定标准(criterion)照这些值写出来,例如「一段占总变化一半以上算主要来源」。
|
||||
Reference in New Issue
Block a user