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

数据目录要给 Agent 补的六类字段业务含义、身份、权限、新鲜度、溯源与动作条件怎么定义摘要数据目录里通常有表名、字段、责任人和存储位置但这些信息撑不住智能体取数模型不知道余额含不含争议项不知道客户该用哪一套 ID也不知道这份数据还能不能用、谁授权它能动。本文把智能体取数前必须拿到的信息拆成六类字段——业务含义、规范身份、权限与用途、新鲜度、溯源证据、动作前置条件给出字段定义、落库结构、契约示例、三种实现路径的取舍以及一套防止字段腐烂的自动校验规则。前言过去两年我在不同企业看到同一类返工智能体接进数据平台了回答也像模像样但业务不敢用。追问下去问题很少出在模型上而是出在数据目录上。举三个真实场景已脱敏口径歧义业务问上月应收余额多少Agent 把两张表 join 起来算一张报的是已核销后余额一张报的是含争议项余额。数字很精确含义是错的。身份错配客户在 CRM 里叫cust_id在财务系统里叫partner_no在数据仓库里叫member_key。Agent 用错一套就出现答案正确、对象错误——它确实回答了正确的余额只不过是别人的。权限绕行某个报表的访问控制做得很严但 Agent 通过统一检索接口拿到同样内容。访问控制被检索能力绕开了。这三个场景的共性是我们的目录记录了数据是什么但没有记录这份数据能不能被 Agent 用、怎么用、用到什么程度。企业现有数据目录的技术元数据和业务元数据基本够用缺的是第三层——面向消费与动作的准入信息。行业里这两年的说法叫数据契约data contract或智能体数据层本质是同一件事把给 Agent 用这件事的前置条件写进数据本身的描述里而不是写在使用者那一侧的代码里。下面把这件事拆成六类字段逐类给出定义与落库方式。一、先看缺口目录里有什么、缺什么目录已有典型Agent 实际需要缺口表名、字段名、类型这个度量到底在算什么、单位是什么业务含义责任人、所属系统主键该用哪一套、外部 ID 怎么映射规范身份敏感级别标签谁在什么用途下可以读/写、写到什么程度权限与用途更新频率T1、每小时这份数据现在算不算过期、能容忍多久新鲜度血缘上下游这条答案依据了哪些具体记录与策略版本溯源证据无允许的状态迁移、动作前必须具备的审批动作前置条件关键差别在最后一行。传统目录服务的是人人看到余额会自己判断语境Agent 不会。所以凡是靠常识补全的信息都必须显式写成字段。二、六类准入字段的定义与落库1. 业务含义business_meaning不只是加一段中文注释而是把度量口径的可变项列全计量单位与币种元/万元人民币/美元统计主体法人主体、账套是否含税、是否含争议项、是否含冲销时间口径业务发生日 / 入账日 / 系统写入日同义词与别名业务口语里的叫法。business_meaning:definition:应收未收余额不含争议项不含已核销unit:CNYentity:法人主体集团公司本级includes_disputed:falsetime_basis:入账日synonyms:[应收余额,AR balance,未收余额]缺失后果数值正确、语义错误——最难被发现的一类错误因为报表能跑通、数字能对上对的是错的口径。2. 规范身份canonical_identityAgent 不做主数据治理但它必须知道用哪一套 ID 作为连接键以及外部系统 ID 怎么映射过来canonical_identity:primary_key:customer_master.cust_uidexternal_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:truepurpose_binding: required是防止权限绕行的关键Agent 每次取数都要带上用途无用途的请求直接拒绝。这样统一检索就不会成为访问控制的旁路。4. 新鲜度freshness必须拆成三个时间而不是一个更新频率字段含义示例source_timestamp数据在源系统产生的时间2026-10-12 23:40ingested_timestamp入湖/入仓时间2026-10-13 02:15max_staleness业务可容忍的最大滞后6 小时max_staleness是最容易被跳过、又最有价值的一项。没有它Agent 无法判断昨天的支付状态能不能用于今天生成催收话术。超过阈值的正确做法是明示不可用而不是照样返回但标注一下。5. 溯源证据provenance让每一条答案事后可查provenance:record_ids_field:row_keyquery_params_capture:true# 记录实际执行的查询条件policy_version:policy-2026.10.3evidence_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_idforbidden:[delete,bulk_update,schema_change]dry_run_first:trueforbidden白名单式禁令比提示词里写一句不要删库可靠得多。事实已经反复证明越权动作靠人写提示词拦不住靠数据结构拦得住。三、六类字段汇总表#字段必填缺失时的典型故障建议校验1业务含义是口径歧义数字对、含义错同义词冲突检测、单位必填2规范身份是答对问题答错对象映射缺失率 1%3权限与用途是检索绕开访问控制无 purpose 请求拒绝率4新鲜度是用过数据做实时决策实际滞后 max_staleness 告警5溯源证据是答案无法追溯证据引用非空率 100%6动作前置条件有写权限时必填越权写入、误删禁区动作触发计数四、怎么落库三条实现路径的取舍路径做法优势代价适用A 扩展目录在现有元数据模型上加扩展属性见效快不惊动研发与运行期耦合弱容易只写不用起步阶段、存量资产批量补齐B 契约即代码契约存 GitCI 里校验发布时随版本走强约束、可评审、可回滚需研发流程配合核心实体与高敏数据C 运行期策略服务Agent 取数前实时查权限与新鲜度最准能拦住运行时风险延迟与复杂度最高有写权限、跨租户的场景我的建议是组合不是选一个A 打底——先把存量资产的含义、身份、新鲜度补进目录覆盖率优先B 管住核心——对 20~50 个核心实体客户、产品、合同、账户等写正式契约进版本控制C 只对会动手的场景启用——凡是 Agent 有写权限的一律走运行期策略校验不给例外。一句话取舍覆盖面靠 A约束力靠 B风险兜底靠 C。一上来就要求全量上 C项目大概率死在中途。五、让字段不腐烂六条自动校验字段写进去只是开始半年后没人更新的目录字段比没有更危险因为它看起来是可信的。建议把下面六条做成自动巡检#校验项规则节奏1新鲜度超阈实际滞后 max_staleness持续 2 个周期小时级2身份映射缺失映射缺失率 1% 或出现1:N未确认项日级3策略版本过期policy_version落后当前版本日级4证据引用为空授权动作类请求无evidence_ref实时拒绝5别名冲突同一别名指向两个不同口径周级6动作条件缺失有写权限资产未填forbidden周级配套加一道准入卡口新资产登记时前五类字段为必填缺项不予登记。把要求卡在入口比事后补数据便宜一个数量级。六、四个坑坑一把准入字段当文档写。写成 Word 附件、放在共享盘里Agent 读不到。契约必须机器可读YAML/JSON/表结构都行唯独不能是文档。坑二六类字段一次全上。存量资产上万一次全补完不现实。先补有写权限 高敏 高频消费的三类资产其余按消费热度排期。坑三只填字段不做校验。没有自动巡检的字段会在三个月内腐坏。字段的价值 定义 × 校验频率。坑四把权限判断交给模型。让模型根据用户角色自己决定能不能返回等于把访问控制做成概率事件。权限必须在数据层判定。总结第一数据目录缺的不是元数据是面向消费与动作的准入信息。靠人补全的语境对 Agent 必须显式化。第二六类字段的最小集是业务含义、规范身份、权限与用途、新鲜度、溯源证据、动作前置条件。前五类所有资产必填第六类有写权限必填。第三实现路径组合使用目录扩展打底、契约即代码管核心、运行期策略服务兜底风险。第四字段必须机器可读、可校验、卡在登记入口。否则会腐烂而腐烂的字段比缺失更危险。第五溯源四要素——记录 ID、查询参数、策略版本、证据引用——是让答案可被追问的前提。一句话先把给 Agent 用的数据应该长什么样写进目录再谈让 Agent 用它。顺序反了返工成本会落在业务侧。你们数据目录里现在有可容忍滞后和动作前置条件这两类字段吗如果只补一类你会先补哪一个欢迎评论区交流。标签数据目录、元数据、Data Agent、数据治理、数据契约