语义层 101：把业务口径写成文档，让数字员工按口径问数

数据库只提供表、字段和外键。它能告诉数字员工「检验结论」是一列整数，取值有 2、3、4，却不能说明哪个取值代表合格。同一份数据，一个人按「4 算合格」得到 33.3%，另一个人按「2、3、4 都算合格」得到 100%，两个数字都能从数据里算出来，差别只在口径。

语义层文档就是把这些口径写下来的地方：一行代表什么业务对象，两张表怎样关联，每个编码的业务含义，指标的分子、分母与时间字段，以及尚未确定、需要人工回答的问题。文档保存在数据源所在资料库的根目录，文件名为「数据源名-语义层.md」，有权限的同事都能打开阅读和修改。

与只在对话里临时约定相比，文档化的口径有三点不同：下一次问数不必重新解释；每条口径带着证据与置信度，能区分「查过」与「推测」；使用者确认过的条目受保护，数字员工后续更新时不会改写。

文档正文先用一段给人看的摘要说明结论、口径与样本量，再用一段结构化内容供数字员工读取。结构化部分分为六块：前两块可以由结构扫描直接起草，中间三块需要既有定义、当前数据源的查询证据或使用者确认，最后一块记录尚未解决的问题。

语义层依附于资料库中的数据源。在「资料库」中新建或选择一个资料库，绑定数据库连接后，系统会扫描表、字段、主键、外键与注释，列表中显示「已连接的只读数据库」和「扫描成功」。这一步只读取结构，不读取业务数据。

建议一个数据源对应一个资料库，并让负责该业务的人拥有编辑权限：语义层文档保存在这个资料库的根目录，后续的审阅、修改和审核都在这里完成。若资料库只有只读权限，数字员工会把文档作为可下载的文件交付，由使用者上传到资料库。

在对话中说明目标即可，例如「为已连接的数据源建立语义层，并回答本月各事业部报验合格率」。不需要预先写出字段名、公式或参考 SQL；如果已经有明确的定义，可以一并写出，数字员工会直接沿用而不再重复确认。

数字员工读取数据前会申请「只读问数授权」。卡片上写明数据源、Schema、允许查询的表、单次返回的行数与字节上限以及有效期；确认后显示「已授权，可发送问数」。授权绑定当前会话，到期后需要重新授权，界面会提示。

授权之后，数字员工按固定顺序工作：先在资料库里查找是否已有该数据源的语义层文档；再用授权范围内的结构起草业务对象与关系；然后用聚合查询核对取值分布与时间范围，形成指标草案。整个过程只发只读查询，不会把明细数据写进文档。

遇到会改变结果、而现有证据无法消除的歧义时，数字员工会暂停并显示「数字员工需要你的输入」。图中的例子是检验结论编码：数据里出现了 2、3、4 三种取值，哪些算合格直接决定合格率的分子。提问同时给出每个选项下的合格率预览，使用者可以直接判断哪一个符合本单位的规定。

已有明确定义的事项不会被重复询问；只影响展示方式、不改变口径的细节也不会打断流程。典型需要确认的三类问题是：指标的分子、分母与排除条件；没有外键时两张表的关联键；枚举值的业务含义。

使用者的回答会作为已确认条目写进文档，并标记 confirmed_by: user。如果暂时无法回答，可以在输入框中说明，数字员工会把它记入开放问题，按物理记录先给出可核对的统计，不替使用者做业务判断。

构建完成后，数字员工会报告文档名、覆盖的对象与指标数量、verified 与 proposed 各多少条、实际跑过的核对查询，以及保存状态。文档以草稿状态出现在资料库中，可以像普通文档一样在编辑器里阅读和修改，也可以下载后修改再上传。

只有经过审核且处于启用状态的语义层文档才会被后续问数加载。这一步是有意设计的：数字员工可以起草口径，但让口径生效的是负责该业务的人。审核前，建议对照本单位的质量规定逐条检查代码值与指标定义，并抽一个熟悉的批次核对数字。

每次保存都会核对文档版本。若同事已在此期间修改，编辑器会提示「文档版本已更新，请刷新后再编辑」，不会静默覆盖。数字员工更新文档时遵守同一规则：先读回当前内容再逐条合并，使用者确认过的条目保持原样，有冲突的新证据写进开放问题而不是直接改写。

数据库结构发生变化（例如重新扫描后结构哈希改变）时，数字员工会复核受影响的条目并列出可能过期的确认项，其余内容保留。

文档启用后，直接用业务语言提问：「本月各事业部报验合格率」。数字员工从文档中取出「报验合格率」的分子、分母与时间字段，按「事业部」分组，生成一条结构化查询；不再需要重新解释合格编码。

每条结果都附带来源信息：查询对象、返回行数、是否完整返回、结构版本，以及展开后的「查看来源详情」。系统同时把本次使用的语义层文档摘要记录到查询账本，之后复核时可以确认这个数字是按哪一版口径算的。

若问到的指标文档里没有，数字员工会如实说明并询问是否新建，而不是自行补一个定义写回资料库。当前版本可直接编译的命名指标为计数与比率两类，支持按日、周、月等时间分桶；求和、均值一类的汇总仍按原字段聚合给出，界面同样显示来源。

得到数字之后常见的追问是「为什么工程事业部是 0」或「这个月和全库有没有差别」。诊断沿用同一份文档：按事业部与结论编码重算分布，说明每个比率的分子分母来自哪几行，再与上一轮结果逐项比对，指出数据或口径是否发生变化。

图中的例子里，全库五条报验记录都落在当月，因此「本月」与「全库」结果一致；这类结论会连同实际返回的行数一起写出。凡是证据不足以下结论的事项，会放在「仍未确定的事项」中，等待补充数据或使用者说明。

诊断结果可以回写到文档的开放问题或口径说明中，也可以保存为数据应用供团队查看。写回文档时同样经过版本核对与审核流程。

这项功能在当前版本中的边界需要事先了解，以便安排适合的场景。

一份经过审核的语义层文档，价值在于之后每一次问数、每一次追问都不必重新解释口径。团队可以把它当作数据口径的公共说明书来维护：新增指标时补一条，规定变化时改一条，并保留审核记录。