mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 00:21:58 +00:00
ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
197 lines
14 KiB
Markdown
197 lines
14 KiB
Markdown
[English](../en/data-catalog.md) | 简体中文
|
||
|
||
# 数据目录
|
||
|
||
这篇讲数据目录：它记什么、怎么起草和审阅、数据剖析、SQL 检查、大库的探查范围，以及结构和取值变化。给搭建者和管理员看。接入数据源见[数据源与表格导入](data-sources.md)。
|
||
|
||
## 为什么要数据目录
|
||
|
||
表名和字段名说不清业务：一行代表一张门票还是一次检票，`visitor_count` 能不能按天相加，两张表按哪一列连、连上之后会不会一对多。助手建图、agent 写 SQL 时只能猜；猜错了，查询照样能跑，数却是错的。
|
||
|
||
数据目录把这些事实记下来，交给三处读：
|
||
|
||
- **助手建图**：系统提示里每个库只有一行概览（表数、几张有目录、有没有遮罩），不列表名和字段。助手要看表时自己查看，服务端一次给齐（见[按需查看](ask-data.md#按需查看)）。
|
||
- **运行时查结构**：`db_schema` 返回表结构时附上目录。**遮罩列只给列名和类型**：它的注释、目录里这一列的中文名、码值和说明都不交给模型。助手查看、`db_schema`、`/api/datasources/{id}/schema?table=` 是同一份说法；代价是运行时 agent 看到的目录少了遮罩列那部分。
|
||
- **SQL 检查**：按目录查出会算错数的写法（见下文）。
|
||
|
||
## 目录记什么
|
||
|
||
- 每张表：中文名、粒度、表类型、业务主键、业务日期、有效记录条件、去重规则。
|
||
- 每个字段：含义、单位、度量类型、码值。
|
||
- 表与表的关联。
|
||
|
||
目录只记数据事实，不记计算公式。「在园人数是存量，不能跨天相加」进目录；「环比 =（本月 − 上月）÷ 上月」进口径卡。这也是不另做一层指标语义层的原因：口径已经由口径卡和版本固定在管，再造一层就会出现两份口径。
|
||
|
||
### 来源和状态
|
||
|
||
目录里每一项都带来源和状态：
|
||
|
||
| | 取值 |
|
||
|---|---|
|
||
| 来源 | 数据库注释、外键、命名推断、数据剖析、模型起草、人工 |
|
||
| 状态 | 推断、已验证、已确认、已驳回 |
|
||
|
||
- 推断的项只作提示；已验证、已确认的才进入错误级检查。
|
||
- 驳回的项保留编号，下一次起草或推断不会把它带回来。
|
||
- 码值表可以标「已列全」。
|
||
|
||
## 起草
|
||
|
||
- 探查时读外键和唯一约束；按 `xxx_id`、`xxxId` 推断关联，表名带业务前缀的也认。
|
||
- 可以让模型起草：中文名、粒度、表类型、业务主键、业务日期，以及每列的含义、单位、度量类型。
|
||
- 导入表格的数据源已有系统按核对结果生成的说明，目录不重复、也不改写它。
|
||
- 数据库注释就是表名、列名本身，或者是标识符写法的，不记进目录（不当中文名，也不当说明、含义）。
|
||
- 数据源上存的「起草要求」和这次的补充说明一起交给模型，帮它理解业务、统一用词。它们不能推翻「只记数据事实」的规矩，交回的内容照样逐项校验。
|
||
- 用哪个模型：在「设置 → 偏好设置」的「起草模型」里选，空着跟随助手的模型。
|
||
|
||
### 模型起草
|
||
|
||
- 作为后台任务逐表进行，每张表记下状态和原因。写完一张就并入目录；宽表每写完一段就并入。
|
||
- 关掉对话框不停。可以停止，也可以只重试失败的表；清单上标出上次起草失败或只完成一部分的表。
|
||
- 停止、服务重启时，已经写进目录的段保留。服务重启时没跑完的任务标成中断，不会自己续跑；点「重试」重新起草这些表，已写进的不会丢。
|
||
- 同步起草和后台任务互斥。
|
||
- 每次调用最多 40 列。宽表先起草表级的项，再把列均分成几段起草；按表的先后排队，不插到窄表前面。
|
||
- 保留模型的思考，输出额度 32768；服务方不收时退回 8192。
|
||
- 重新起草时，模型这次留空或没通过校验的项，不删以前起草的。
|
||
- 模型拿不准、留空的列（目录里还没有中文名和含义的）逐表记下，可以补充起草要求后重起草。
|
||
|
||
### 起草的止损规则
|
||
|
||
起草不设总时长上限，靠止损规则和手动停止：
|
||
|
||
- 额度用完或超时，就把这一段拆小再问。超时的两半同时问；拆到每段 10 列仍接连超时，就不再拆。
|
||
- 累计拆小两次后，新开始的段减半，最低 10 列。
|
||
- 每段连同它分开、拆小的各块，最多调用 8 次。进度上看得到一段被分成了几块。
|
||
- 缺的表和列只补问缺的；被截断的回复先留下已经写完整的部分。
|
||
- 最近 10 次调用有 7 次没写出来时，后面的段不再拆小；同一张表接连 3 段都没写出来，就跳过它剩下的段。
|
||
- 最近 6 次调用有 4 次没写出来时，提醒换模型。
|
||
- 没写出来的原因写清是第几段、哪几列；「已拆小重试」只跟在真拆过的段后面。
|
||
|
||
### 防错事实的提议
|
||
|
||
模型起草时，另外提议「有效记录条件」（一段 SQL 条件）和「去重规则」，各带依据。开了剖析的数据源，会把目录里的码值一起交给模型（遮罩列不给）。
|
||
|
||
- 条件按数据源的方言用 sqlglot 解析。只能引用这张表的列，不能有子查询、聚合、窗口函数，只允许几个常用函数；不符合的不收，逐表说明里写原因。
|
||
- 开了剖析的数据源上，经只读守卫数出排除比例。排除 0% 或 100% 的不收；收下的在说明里写「剖析核对：排除 x% 的行」。
|
||
- 这些都记为推断。SQL 检查的错误级规则只认人确认过的；这些提议在审阅队列里排在前面。
|
||
|
||
## 审阅与修改
|
||
|
||
### 审阅队列
|
||
|
||
- 只列推断的项，按「表被运行用到的次数 × 这一项多影响数字 × 来源」排序：有效记录条件、去重规则、业务日期、关联关系最前，业务主键、度量类型次之，中文名、含义、单位靠后。每项写明排在这里的理由。
|
||
- 可以按类别和表筛选，多选后批量确认、驳回或撤销审阅。逐表加乐观锁，冲突逐条标出。
|
||
- 看得到一张表被哪些运行用过，以及常用表、全部表和影响数字的项各确认了多少。
|
||
|
||
### 表助手
|
||
|
||
在表详情页里和助手对话，完善这一张表：
|
||
|
||
- 它看得到表结构、目录现状（每项的来源和状态）、关联关系、剖析结果、起草要求和上次起草留空的列。遮罩列只给列名。
|
||
- 它按你的指示成批提出修改，每项带改前、改后和依据，校验规则和目录相同（公式不收，列名要在表结构里）；拿不准的会反过来问你。
|
||
- 只在开了剖析的数据源上，它才经只读守卫跑查询核实：每次请求最多 5 条，结果先遮罩。
|
||
- 提案攒在「待保存的修改」里，确认后一次保存（一次最多 200 项），记为人工确认。每项的依据另存为这一项「确认时的依据」，和备注分开，在表详情里看得到；撤销审阅回到推断时去掉。
|
||
- 对话不存服务端。它只改目录，不碰业务库。
|
||
|
||
### 在对话里纠正
|
||
|
||
在对话里说「status=9 表示作废」，助手会给出一条目录修改提案，列出改前、改后和理由。人确认后才保存，理由记为这一项「确认时的依据」。公式不收，留给口径卡。
|
||
|
||
## 导出与导入
|
||
|
||
把目录导出成一个 JSON 文件（全部表的目录、各项状态和起草要求），在另一个实例或数据源上导入：
|
||
|
||
1. 先预览：哪些表、列对得上；每一项会新增、更新还是保留；冲突和跳过的逐条列出。
|
||
2. 人确认、驳回过的项照带。目标里已经确认过、但值不同的，保留目标的，记成冲突。文件里推断的项只填空缺。表结构里没有的列跳过，写明原因。
|
||
3. 起草要求只在目标没有时写入。
|
||
|
||
有起草或剖析在进行时不能导入。
|
||
|
||
## 数据剖析
|
||
|
||
剖析用只读查询核对目录里的推断、补上统计事实。默认关闭，按数据源开启。
|
||
|
||
- 作为后台任务逐表进行：每张表看得到检查项进度、查询数、用时和正在核对哪一项。关掉对话框不停；可以停止，也可以只重试没做完的表。服务重启时没跑完的任务标成中断，不会自己续跑。
|
||
- 预算按表算，缺省每张表最多 40 条查询、60 秒。一张表用完只停它自己，下一张照样满额。
|
||
- 整次不设上限，靠止损和手动停止：连续 3 条查询失败，或最近 10 条有 7 条超时，就停下，不给业务库加压。
|
||
- 缺省一张表做完再做下一张。数据源设置里可以改成同时剖析 2–3 张，同一时刻对业务库最多这么多条查询。
|
||
- 每张表的查询一条一条发，只读，经过守卫。大表用统计信息估算行数；遮罩的列不取样。
|
||
- 发过的每条查询都留痕，取值换成「?」，抽到的键值不进 AgentLab 的库。
|
||
- 抽样核实推断出的关联，补上覆盖率和基数，站得住的升为已验证。状态列给出码值候选，含义等人填写。
|
||
- 剖析设置里的「核对键值数」：`DISTINCT … LIMIT` 取的不是随机样本。
|
||
- MySQL / MariaDB 上，文字列的剖析说明写明排序规则；ENUM 列补上数据里没出现的取值；日期列写明排除了几个无效日期。
|
||
- 表清单有「剖析」一列，表详情里有上次剖析的结果。
|
||
|
||
缺省只剖析「需要剖析的表」：从没剖析过、上次没做完，或者之后又出现了待核实的关联、新的码值列或日期列的。同一个数据源上，起草和剖析排队串行；范围在开始剖析时按当时的目录定，所以起草完接着点剖析就行。
|
||
|
||
### 取值观察
|
||
|
||
剖析范围选「取值观察」或定时维护时，还会观察取值：行数、码值分布（包括人工确认过的码值列）、最新业务日期、最近 35 天每天的行数。
|
||
|
||
- 和同一口径（同样的取样方式）的历史比，比出新码值、比例剧变、断档、缺天、量跌、行数大起大落，记进变化记录（见下文）。
|
||
- 标了「已列全」的码值表出现目录里没有的取值时，系统撤销「已列全」，目录升一版。这是机器唯一会自己写进目录的事；新取值的含义仍要人填。
|
||
- 遮罩列不观察。
|
||
|
||
## 版本与提醒
|
||
|
||
- 目录随表结构快照冻结进证据，每次运行用的是哪一版查得到。
|
||
- 发布时记下模板引用的表的目录版本；正式运行时目录有变化就提醒。agent 运行时才写 SQL 的，按「可能涉及」单独提醒。只提醒，不拦运行。
|
||
- 从发布版本发起的正式运行，这一版引用的表结构在发布之后变了时，运行里多一条「表结构变化」提醒（`schema.drift`，在封存范围内）。
|
||
- 审阅改了影响数字的那几项（有效记录条件、去重、业务日期、关联、业务主键、度量类型），或者表结构删了表、删了列、改了列类型时，用过它的答案标「依据有变」（见[口径账本](evaluation-and-ledger.md#召回)）。
|
||
|
||
## SQL 检查
|
||
|
||
按目录检查七类问题：
|
||
|
||
1. 一对多关联后重复计算；
|
||
2. 存量跨时间相加；
|
||
3. 比率被相加或平均；
|
||
4. 漏了有效记录条件；
|
||
5. 码值不存在；
|
||
6. 没用约定的业务日期；
|
||
7. 关联条件对不上已知关系。
|
||
|
||
检查用在四处：助手自查时交回修正；受管模板发布时挡住；运行时标在查询快照上；契约指标的来源查询有错误时，出具降档。
|
||
|
||
解析不了的写法一律跳过：宁可漏报，不误报。错误级规则只用已验证、已确认的目录项。
|
||
|
||
## 大库：探查范围与按需加入
|
||
|
||
几千张表的库不必全部读进来。
|
||
|
||
- 探查先建一份全库的对象索引：每种数据库一条字典查询，记名字、类型、注释、估算行数。
|
||
- 再按「探查范围」的规则读范围内的表：支持通配，排除优先；缺省最多 500 张，上限 2,000。
|
||
- 有数据目录的表、已发布模板写死的 SQL 用到的表，一律在范围内。
|
||
- 超过 500 张表、又没设探查范围的库，第一次探查会被拒绝，并说出命中了多少张。先在「探查范围」里设规则，或调高上限。
|
||
|
||
运行时和助手查看都先检索：
|
||
|
||
- 助手查看和运行时的 `db_schema__` 先按需求检索（BM25；遮罩列只用列名）。
|
||
- `db_schema__` 不传表名时只列前 50 张，并说清另有多少张；可以用 `keyword` 检索。
|
||
- 点名范围外的表，会当场只读地读结构、加进范围并留痕（每次运行最多 8 张）。
|
||
- 「表已不在」只在表真被删了时说；范围外、读不到结构、索引里从来没有，各自分开说。
|
||
- 剖析得到的行数和日期范围也交给助手和 agent，附一句「只供写查询参考，不能作为回答里的数」。遮罩按当时的设置重新过滤。
|
||
|
||
## 结构变化与取值变化
|
||
|
||
- **结构变化**：探查时每张表记一个结构版本，和上一次读到的比：加删列、改类型、改可空、改注释、主键 / 唯一约束 / 外键的增删。疑似改名只说「可能是改名」，不下结论。一张表第一次被探查时只建基线，不出变化。
|
||
- **取值变化**：取值观察和同一口径的历史比。大表照实写口径（整表、窗口、块采样、前 N 行），口径不同不比。
|
||
|
||
两种变化记在同一份变化记录里。
|
||
|
||
### 在哪看、怎么处理
|
||
|
||
- 数据目录的「变化」视图按「要处理 / 提醒 / 说明」分组；数据源卡片上的角标是要处理的条数；表详情里有「结构与取值变化」一节。
|
||
- 每条写明影响面：说到这些列的目录项和它们的状态、写死了这一列的已发布模板、哪条 SQL 现在会报列不存在。
|
||
- 处理动作：「清理目录项」「加入码值」「重新起草」「重新剖析」「知道了」「误报」（误报必须写理由）。动作都落到目录已有的写入上，记下目录版本或建的任务。
|
||
- 机器自己只做一件事：数据证明码值表不再列全时，撤销「已列全」。
|
||
- 有「要处理」的变化时，可以推通知「数据源有变化要处理」，消息里只有源名、条数和链接，不放表名、列名和取值（见[通知](schedules.md#通知)）。也可以作为定时任务的触发事件。
|
||
|
||
### 定时维护
|
||
|
||
数据源卡片上的「定时维护」：
|
||
|
||
- 选步骤（探查结构、剖析需要的表、取值观察，可多选）和低峰时段，存成一条目标为这个数据源的定时任务。缺省没有。
|
||
- 和起草、剖析在同一个数据源上排队；没执行的步骤照实记原因。
|
||
- 这类定时任务不收 Webhook（回 422），通知走「设置 → 通知」的渠道订阅。
|