用 cz-cli 驱动 Agent 建模分析域
如何阅读本指南
本指南教你如何与 Agent 协作完成分析域的工作，而不是教你怎么操作 Web 页面或背 CLI 命令。
和 Agent 协作的方式是对话。你描述想做什么——"给客户表加个别名""补几个指标""检查域的完整性"——Agent 理解意图后执行操作并反馈结果。你不需要知道配置项在哪个菜单下、命令有几个参数、表名是什么格式。你需要知道的是分析域有哪些概念、每一步需要你提供什么样的信息和判断。
本指南分三个部分：
- 第二章：分析域的概念模型——它由哪些部分组成，每部分做什么，建好后能回答什么问题
- 第三章 + 第四章：两个实践案例——单域深度打磨（银行域，从 40 分到 92 分）和四域批量建设（物流/保险/医疗/制造），展示完整的对话协作过程
- 第五章：域建成后的持续治理场景——日常维护中常见的问题和对应的对话模式
Agent 在背后执行的 CLI 命令列在附录，供你了解工作机制，但不要求记忆。
一、引言
痛点
分析域不是建完就完了。数据持续接入、规则不断调整、用户反馈迭代——治理是长期的。但传统方式（Web 页面逐项操作）让这件事变得让人不想做。
| 场景 | 实际操作 | 心理感受 |
|---|---|---|
| 用户反馈"搜不到客户名" | 可能只是某个字段缺了别名。但修复它需要：打开页面 → 找到域 → 找到那张表 → 找到那个字段 → 点编辑 → 输入别名 → 保存 | "又要去点一遍..." |
| 5 个域需要巡检 | 检查指标覆盖率、字段描述率。页面只能逐个打开查看 | "等有空再说吧..." |
| 加了一张新表 | 加表、补别名、定义指标、配 JOIN——每次同样的组合 | "我先忙别的，这个不急" |
| 监管规则变更 | 改一条知识描述。要上传文件、建文件夹、重新绑定 | "才改一行字而已至于吗" |
每次操作本身不难，也不久。但琐碎、重复、流程不连贯——积累起来就是负面情绪。 用户会拖延、跳过非紧急的维护任务，最终导致分析域质量退化，Data Analytics Agent 回答问题开始变得不准确。不是因为能力问题，是因为让人烦。
负担从操作转向决策
Agent + CLI 不消除工作量——它转移工作量。
工作中心的转移：从"操作页面"转向"描述需求"。用户不再需要知道配置项在哪个菜单下、表名是什么格式、参数有几个——这些由 Agent 和 CLI 处理。但用户需要能清楚表达：我要改什么、改成什么样、期望什么结果。
这并不比学页面操作更容易或更难——难度类型变了。需要的是对分析域概念的准确理解（知道有"字段别名"这个东西），以及对业务需求的准确表述（知道这个字段在业务上应该叫什么）。
实际体验：
- 改别名：不需要知道表在哪个 schema、字段在哪。但需要知道加的是"别名"而不是"描述"，以及正确的业务名称
- 加指标：不需要知道
的格式。但需要理解指标的含义（COUNT 还是 SUM？需要 ROUND 吗？）--table-name - 质量巡检：不需要逐个域点开。但需要理解各维度的评分含义，判断哪些缺失项需要优先处理
从"操作型负担"转向"决策型负担"。操作的烦被拿掉了，决策的难度还在——这是合理的，因为决策本来就需要人来判断。
解决方案
用 Agent 承接操作，人只负责决策。
Agent 的方法论基于三个设计原则：
把操作层交给机器。67 个字段加别名——人不需要做重复的体力劳动。Agent 按照同样的标准执行每一个，不会疲劳、不会跳过。
把记忆交给系统。治理是碎片化的：今天加个表，下周改条规则。人不需要回忆"上次改到哪了""这个域的表名叫什么"——Agent 从当前域状态出发，上下文不中断。
把推断交给 LLM。看到
loansprincipalinterest_rate这三件事解决了"操作型负担"——重复、记忆、推断。剩下的"决策型负担"——判断改什么、改对了吗、优先级怎么排——仍然是人负责的部分。
二、分析域是什么
一个分析域是把物理表翻译成业务语言的六层模型。每层不需要达到完美才能用——可以一步步叠加，每一层建完就立即生效。
第一层：表接入
做什么：告诉 Agent 数据在哪个 schema、有哪些表。
用户需要提供：schema 位置、要接入的表。
完成后能回答：
此时 Agent 只知道表和列名，不理解业务含义。
第二层：字段语义
做什么：给字段加中文别名和业务描述。
用户需要提供：哪些字段是业务关键字段（名称、金额、状态、日期类）。Agent 可以推断哪些字段需要别名，但业务描述需要用户确认。
完成后能回答：
Agent 现在知道"客户类型"对应
customer_typebalance额外收获：虚拟列。有些字段在表中不存在，但业务上需要——比如"信用使用率 = 欠款/信用额度"。Agent 可以帮你定义这些派生字段。
第三层：表关联
做什么：告诉 Agent 表之间的 JOIN 关系。
用户需要提供：描述关联——"customers 通过 customer_id 关联到 accounts"。Agent 能自动发现同名列之间的关联，但需要你确认。
完成后能回答：
Agent 现在能跨表查询，自动生成正确的 JOIN SQL。
第四层：指标
做什么：定义业务上关心的统计值。
用户需要提供：需要哪些指标——"交易总额、平均利率、逾期率"。Agent 能根据表结构推断常见指标，然后你确认表达式是否正确。
完成后能回答：
Agent 不再需要每次推理聚合逻辑——指标已经定义好了，直接给出数值。
第五层：知识
做什么：告诉 Agent 业务规则、术语含义、判断标准。
用户需要提供：行业知识——"逾期超过 30 天算严重""风险评分 60 以上为高风险""房贷逾期率警戒线是 3%"。通常以文档形式提供。
完成后能回答：
Agent 不仅给出数值，还能做出业务判断——把数据放进行业语境中解释。
第六层：Answer Builder
做什么：把高频分析场景固化为预置模板。
用户需要提供：哪些分析是反复需要的——"贷款逾期监控""卡消费商户分析"。Agent 帮你生成 SQL 和分析面板配置。
完成后：用户说"贷款逾期监控"即可打开完整分析面板，不需要每次描述分析需求。
三、实践示例一：单域深度打磨
银行数据在
bnk_banking3.1 先看现状
域已经建好了（ID 28），但只做了最基础的表接入。
用户："帮我看下新建的 banking domain 的语义建设情况"
Agent 查看域详情：
这就是起点——表有了，但 Agent 完全不懂业务含义。用户决定继续建设。
3.2 开始补全
在 Agent 报告了域的状态（9表/0指标/0知识/40分）后：
就两个字。Agent 理解了——需要把银行域从当前 40 分状态补全到可用水平。Agent 列出接下来要做的事：67 个字段描述、16 个指标、6 条知识、8 条 JOIN、4 个虚拟列，然后开始逐项执行。
字段描述和别名。Agent 给 67 个字段逐一设置业务描述，给 27 个关键字段加中文别名。期间不需要用户逐一确认——Agent 根据字段名（
customer_namerisk_scorebalance指标。Agent 在每张事实表上定义核心聚合。需要用户判断的（如"逾期率的分子用哪个字段？"），Agent 会停下来问。
知识。Agent 用文件路径创建了 6 条业务知识（客户分类、贷款类型、逾期率计算、信用卡指标、商户类别、交易类型）。创建完后——
3.3 知识不可见
Agent 检查：CLI 的
knowledge list --domain-id 28Agent 判断根因：知识有两种存储路径——API 文本条目和知识空间文件节点。当前用的是 API 方式，页面只渲染文件节点。Agent 切换方式：把知识内容写成 Markdown 文件，按文件上传路径重新创建（上传 → 建文件夹 → 移入 → 绑定域）。
Agent 确认：是的，
knowledge create3.4 表关联失败
Agent 尝试用自动发现：
domain joins discoverAgent 改变思路：不再依赖自动发现。切到数据所在的实例，用 SQL 逐对验证 FK 数据匹配度（
SELECT COUNT(DISTINCT a.customer_id), COUNT(DISTINCT c.customer_id) FROM accounts a LEFT JOIN customers c...确认 FK 存在但自动发现引擎有 bug。Agent 的临时方案：把 8 条 JOIN 规则写入 domain 的 custom prompt，让 Agent 生成 SQL 时参照这些规则。功能等效，但不走正式的 JOIN 元数据配置。
后续升级到 v1.17.18 后，
domain join create3.5 持续追加
Agent 给 27 个字段加了中文别名（客户名、风险分、余额、贷款类型、本金、年利率...）。
Agent 补了 6 条业务知识。
Agent 理解为补 Answer Builder 和虚拟列。创建了 3 个 AB（贷款逾期监控、卡消费商户分析、客户存款总览）和 4 个虚拟列（信用使用率、交易月份、逾期标记、卡交易月份）。
3.6 最终检查
用户："看一下银行域的完整状态"
3.7 这个过程的真实模式
回看整个对话，不是"一句指令 → 完美结果"的直线，而是：
这是分析域治理的常态——边建边验、遇到问题就解决、解决完继续。Agent 的价值不在于一次做对所有事，而在于每轮迭代中：人只需要描述问题和需求，Agent 负责诊断、执行、反馈结果。
四、实践示例二：批量工业化复制
4.1 先探索数据
银行域完成后，用户在 62 个 schema 中系统性地寻找其他可建域的数据。
Agent 切换实例后列出全部 62 个 schema。
Agent 逐一列出四个 schema 下的表，每个都是标准星型模型。筛选后四域可用表分别为 9 / 8 / 10 / 8 张。
4.2 开始批量建设
Agent 并行创建四个域（ID 29-32）。每个域配了名称、描述、3-5 个示例问题。然后批量加表——银行域的教训已经知道参数格式，四个域顺利加完。
Agent 理解了——和银行域一样，四个域都需要从当前骨架状态补全到可用水平。Agent 开始为四个域补指标（每域 5-8 个）、JOIN（每域 4-5 条）、知识（每域 4 条）。
4.3 建设中发现的问题
漏加的表。Agent 在做最终检查时发现数据不一致：
保险域 targetCounts.dataset = 7，但应该 8 张（policies 表缺失）。制造域同理，quality_inspections 没加上。两张表在批量加表时静默失败了——返回成功但未实际生效。Agent 立即补加。
列名对不上。创建物流域的"发货趋势分析"Answer Builder 时，SQL 报列名错误。Agent 查
table columnsshipment_datestat_datedataset ID 映射。创建保险域的 JOIN 时，Agent 把
policyholdersreinsurance_treatiesdomain detail4.4 继续补全
Agent 给四个域补了 Answer Builder（每域 2 个）和虚拟列（跨域 9 个）。其中制造域的"质检合格率分析"第一次创建失败——
CASE WHEN result='PASS'4.5 最终状态
Agent 汇总四个域的建设成果：
4.6 批量建设的真实模式
银行域的教训被复用（知识走文件路径、JOIN 手动创建、加表参数一次带全），但每个新域仍然有自己的问题——列名对不上、表静默失败、ID 映射混乱。Agent 的价值在于：每次发现问题后，不需要人去翻页面找原因，Agent 查详情、诊断根因、执行修复，人只需要确认"修得对不对"。
五、持续治理
域建成后，日常维护同样通过 Agent 完成：
加新表。"bnk_banking 新增了 investment_portfolio 表，加入 banking 域并补字段别名和指标。"
修改别名。"customers 表的 customer_type 别名从'客户类型'改成'客户分类'。"
更新知识。"逾期率警戒线从 3% 更新为 2.5%，更新 banking 域的知识文件。"
质量巡检。"检查五个域的指标覆盖率，列出每个域的分数和缺失项。"
每次操作后，Agent 会返回执行结果和域的最新状态，用户可以立即确认是否达到预期。
附录 A：行业域实体清单
银行 (banking)
物流 (logistics_dw)
保险 (ins_insurance)
医疗 (hrc_healthcare)
制造 (mfg_manufacturing)
附录 B：Agent 背后的 CLI 命令
日常使用中你不需要执行这些命令——Agent 会帮你调。此处列出供查阅，帮助你理解 Agent 的工作方式。
| 操作 | Agent 执行的命令 |
|---|---|
| 建域 | |
| 加表 | |
| 字段描述 | |
| 字段别名 | |
| 虚拟列 | |
| 指标 | |
| JOIN | |
| 知识 | |
| AB | |
| 验证 | |