企业官网建设流程全解析

数据目录要给 Agent 补的六类字段：业务含义、身份、权限、新鲜度、溯源与动作条件怎么定义

摘要

数据目录里通常有表名、字段、责任人和存储位置，但这些信息撑不住智能体取数：模型不知道"余额"含不含争议项，不知道客户该用哪一套 ID，也不知道这份数据还能不能用、谁授权它能动。本文把智能体取数前必须拿到的信息拆成六类字段——业务含义、规范身份、权限与用途、新鲜度、溯源证据、动作前置条件，给出字段定义、落库结构、契约示例、三种实现路径的取舍，以及一套防止"字段腐烂"的自动校验规则。

前言

过去两年，我在不同企业看到同一类返工：智能体接进数据平台了，回答也像模像样，但业务不敢用。

追问下去，问题很少出在模型上，而是出在数据目录上。举三个真实场景（已脱敏）：

• 口径歧义：业务问"上月应收余额多少"，Agent 把两张表 join 起来算，一张报的是"已核销后余额"，一张报的是"含争议项余额"。数字很精确，含义是错的。
• 身份错配：客户在 CRM 里叫cust_id，在财务系统里叫partner_no，在数据仓库里叫member_key。Agent 用错一套，就出现"答案正确、对象错误"——它确实回答了正确的余额，只不过是别人的。
• 权限绕行：某个报表的访问控制做得很严，但 Agent 通过统一检索接口拿到同样内容。访问控制被检索能力绕开了。

这三个场景的共性是：我们的目录记录了"数据是什么"，但没有记录"这份数据能不能被 Agent 用、怎么用、用到什么程度"。

企业现有数据目录的技术元数据和业务元数据基本够用，缺的是第三层——面向消费与动作的准入信息。行业里这两年的说法叫"数据契约"（data contract）或"智能体数据层"，本质是同一件事：把"给 Agent 用"这件事的前置条件，写进数据本身的描述里，而不是写在使用者那一侧的代码里。

下面把这件事拆成六类字段，逐类给出定义与落库方式。

一、先看缺口：目录里有什么、缺什么

关键差别在最后一行。传统目录服务的是"人"，人看到"余额"会自己判断语境；Agent 不会。所以凡是靠常识补全的信息，都必须显式写成字段。

二、六类准入字段的定义与落库

1. 业务含义（business_meaning）

不只是加一段中文注释，而是把度量口径的可变项列全：

• 计量单位与币种（元/万元；人民币/美元）；
• 统计主体（法人主体、账套）；
• 是否含税、是否含争议项、是否含冲销；
• 时间口径（业务发生日 / 入账日 / 系统写入日）；
• 同义词与别名（业务口语里的叫法）。

business_meaning:definition:"应收未收余额（不含争议项，不含已核销）"unit:"CNY"entity:"法人主体：集团公司本级"includes_disputed:falsetime_basis:"入账日"synonyms:["应收余额","AR balance","未收余额"]

缺失后果：数值正确、语义错误——最难被发现的一类错误，因为报表能跑通、数字能对上（对的是错的口径）。

2. 规范身份（canonical_identity）

Agent 不做主数据治理，但它必须知道用哪一套 ID 作为连接键，以及外部系统 ID 怎么映射过来：

canonical_identity:primary_key:"customer_master.cust_uid"external_mapping:-source:"crm" field:"cust_id" confidence:"1:1"-source:"finance" field:"partner_no" confidence:"1:N（需人工确认）"unresolved_policy:"拒绝返回并提示人工确认"

注意confidence这一行。真实企业里 1:1 的映射是少数。把映射质量写进契约，比事后解释"为什么这个客户对不上"省事得多。

缺失后果：正确的问题、正确的数字、错误的客户。金融、医疗场景里这类错误代价最高。

3. 权限与用途（permission & purpose）

权限不是"能不能读这张表"，而是租户 × 用户 × 用途三元组，且读与写必须分离：

permission:read_scope:["tenant:A","role:analysis","purpose:reporting"]write_scope:[]# 默认不给写purpose_binding:required# 取数时必须带 purpose 参数deny_by_default:true

purpose_binding: required是防止权限绕行的关键：Agent 每次取数都要带上用途，无用途的请求直接拒绝。这样"统一检索"就不会成为访问控制的旁路。

4. 新鲜度（freshness）

必须拆成三个时间，而不是一个"更新频率"：

max_staleness是最容易被跳过、又最有价值的一项。没有它，Agent 无法判断"昨天的支付状态"能不能用于今天生成催收话术。超过阈值的正确做法是明示不可用，而不是"照样返回但标注一下"。

5. 溯源证据（provenance）

让每一条答案事后可查：

provenance:record_ids_field:"row_key"query_params_capture:true# 记录实际执行的查询条件policy_version:"policy-2026.10.3"evidence_ref:"duckdb://evidence/answer_20261013_0042.parquet"

四个要素——记录 ID、查询参数、策略版本、证据引用。缺任何一个，"这个结论是怎么来的"就答不上来。

6. 动作前置条件（action_conditions）

这是给"会动手"的 Agent 准备的。允许的状态迁移必须显式列出，而不是留给模型推断：

action_conditions:allowed_transitions:-from:"draft" to:"submitted" requires:"creator_or_reviewer"-from:"submitted" to:"approved" requires:"approval_record_id"forbidden:["delete","bulk_update","schema_change"]dry_run_first:true

forbidden白名单式禁令比"提示词里写一句不要删库"可靠得多。事实已经反复证明：越权动作靠人写提示词拦不住，靠数据结构拦得住。

三、六类字段汇总表

四、怎么落库：三条实现路径的取舍

我的建议是组合，不是选一个：

1. A 打底——先把存量资产的含义、身份、新鲜度补进目录，覆盖率优先；
2. B 管住核心——对 20~50 个核心实体（客户、产品、合同、账户等）写正式契约，进版本控制；
3. C 只对"会动手"的场景启用——凡是 Agent 有写权限的，一律走运行期策略校验，不给例外。

一句话取舍：覆盖面靠 A，约束力靠 B，风险兜底靠 C。一上来就要求全量上 C，项目大概率死在中途。

五、让字段不腐烂：六条自动校验

字段写进去只是开始，半年后没人更新的目录字段比没有更危险（因为它看起来是可信的）。建议把下面六条做成自动巡检：

配套加一道准入卡口：新资产登记时，前五类字段为必填，缺项不予登记。把要求卡在入口，比事后补数据便宜一个数量级。

六、四个坑

坑一：把准入字段当文档写。写成 Word 附件、放在共享盘里，Agent 读不到。契约必须机器可读，YAML/JSON/表结构都行，唯独不能是文档。

坑二：六类字段一次全上。存量资产上万，一次全补完不现实。先补"有写权限 + 高敏 + 高频消费"的三类资产，其余按消费热度排期。

坑三：只填字段不做校验。没有自动巡检的字段会在三个月内腐坏。字段的价值 = 定义 × 校验频率。

坑四：把权限判断交给模型。让模型"根据用户角色自己决定能不能返回"，等于把访问控制做成概率事件。权限必须在数据层判定。

总结

第一，数据目录缺的不是元数据，是面向消费与动作的准入信息。靠人补全的语境，对 Agent 必须显式化。

第二，六类字段的最小集是：业务含义、规范身份、权限与用途、新鲜度、溯源证据、动作前置条件。前五类所有资产必填，第六类有写权限必填。

第三，实现路径组合使用：目录扩展打底、契约即代码管核心、运行期策略服务兜底风险。

第四，字段必须机器可读、可校验、卡在登记入口。否则会腐烂，而腐烂的字段比缺失更危险。

第五，溯源四要素——记录 ID、查询参数、策略版本、证据引用——是让答案可被追问的前提。

一句话：先把"给 Agent 用的数据应该长什么样"写进目录，再谈让 Agent 用它。顺序反了，返工成本会落在业务侧。

你们数据目录里现在有"可容忍滞后"和"动作前置条件"这两类字段吗？如果只补一类，你会先补哪一个？欢迎评论区交流。

标签：数据目录、元数据、Data Agent、数据治理、数据契约