教程：建模并提问¶
大约十分钟，从一个空目录到一套受治理的语义模型，全程只和编程 Agent 对话：连接数据库、 建模型、提问、看一个数字是怎么算出来的、解释它为什么变了、查明细记录。不用写 YAML， 也不用写 SQL。
下面的耗时是在 Claude Code 里用 dosi 0.2.0 实测的，Agent 通过 dosi 的 MCP 工具回答。
Codex 走的是同样的步骤，DeepSeek Harness 也一样，只是通过 dosi 的命令行；这两个
Agent 里没有 Claude Code 专属的 /dosi 和血缘面板。
前置条件
Agent 里已经装好 Dosi 插件：Claude Code、
Codex 或 DeepSeek Harness。建议 PATH 上有
duckdb 命令行：
Agent 建模时用它看表结构，并且以只读方式打开文件。
准备数据¶
示例库里有大约 19 万笔订单，来自 5,000 个客户、500 种商品，时间是 2024 年 1 到 6 月：
（也可以启动 codex，或者在 DeepSeek Harness 里打开这个目录。）用什么语言提问都行，
Agent 会用同样的语言回答。
第 1 步 —— 连接，约 20 秒¶
帮我连上数据
插件找到 orders-200k.duckdb，在 dosi-connections.yaml 里写一条名为 local
的连接，把这个文件加进 .gitignore，然后测试连接。不用回答任何问题：本地文件不需要
口令。你会看到一行说明 local（DuckDB）已经连上。
如果是你自己的数据，这一步会读取 dbt profiles 或 Cube 的 .env，或者问你数据在哪里，
见 Dosi 插件。
第 2 步 —— 建语义模型，约 2 分钟¶
给这些数据建一个语义模型
Agent 边做边说明每一步：
- 用
duckdb -readonly看三张表的字段和行数； - 分层写出
dosi/model.yaml：先是数据集和两条关联，然后是基础指标（全部订单）、 派生指标（只算已完成订单、客单价、取消率），最后是窗口指标（环比、累计、按地区的 排名和占比）。每次保存都会自动校验； - 把指标和直接从表里算出的数字对一遍。
最后它给一段简短的汇报：建了什么、核对了什么、有什么没建。我们这次运行里，它没建 毛利指标（商品有单位成本，但订单里没有数量），还指出从 4 月起销售额下降、取消率上升。 如果它问到业务含义，每个问题都带推荐答案：回答“按推荐的来”，或者自己选。
模型是 Agent 写的，所以指标名和数量每次会有出入；一般是三个数据集、两条关联、十五个 左右的指标。
第 3 步 —— 提问，约 15 秒¶
各地区每个月的销售额是多少？
回答是一句结论、一张表，加一行注明连接和行数：
| 月份 | east | north | south | west |
|---|---|---|---|---|
| 2024-01 | 828,295 | 873,411 | 787,968 | 815,180 |
| 2024-02 | 780,978 | 827,827 | 736,401 | 767,729 |
| 2024-03 | 836,333 | 869,080 | 784,512 | 808,314 |
| 2024-04 | 760,525 | 783,051 | 711,572 | 379,848 |
| 2024-05 | 767,920 | 829,721 | 722,549 | 384,489 |
| 2024-06 | 749,397 | 782,363 | 720,806 | 378,603 |
这里的销售额是已完成订单的金额，也就是第 2 步定下的口径。可以随意追问（“只看 north” “按周看”“环比呢”）；说“给我看 SQL”就能看到 dosi 实际执行的语句。
第 4 步 —— 看一个数字是怎么算的，约 15 秒¶
销售额是怎么算出来的？
Agent 把这个指标一路追到表，用一棵小树回答：销售额在订单金额合计的基础上，只保留
status = 'completed' 的订单，金额由 orders 数据集从 orders 表读出。它还会说明
拆分时怎么关联：地区按下单客户关联，月份按下单日期归属。
在 Claude Code 里，/dosi lineage revenue 会在面板里打开完整的血缘图。想要一个独立的
HTML 文件，直接说要血缘页面就行。
第 5 步 —— 解释变化，约 20 秒¶
二季度销售额为什么比一季度低？
Agent 先用 dosi 的归因按地区和品类拆解，再做一次拆分确认。销售额从 971.6 万降到 797.1 万（−18%），回答把降幅拆成几块，加起来正好等于总数：
| 部分 | 一季度 | 二季度 | 变化 |
|---|---|---|---|
| 西区（全部品类） | 2,391,223 | 1,142,941 | −1,248,282 |
| 东、北、南三区的电子类 | 1,868,003 | 1,348,770 | −519,233 |
| 其他 | 5,456,802 | 5,479,134 | +22,332 |
从 4 月起，西区的订单少了约三分之一，取消率从 8% 左右升到 28%；电子类在各地区的 订单数没变，但客单价降了约 28%。示例数据就是按这两件事生成的，可以拿来检验 Agent 有没有把两个原因都找出来。
第 6 步 —— 查明细，约 20 秒¶
列出金额最大的 10 个订单，带上客户地区和商品类目
这是问记录而不是问汇总，Agent 用 dosi 的 select，客户和商品的关联由 dosi 完成。
示例数据里最大的金额 216.81 有 31 笔订单并列，Agent 会如实说明，而不是随便取 10 笔
当作前十。
现在你有了什么¶
把 dosi/ 提交到仓库：拉取仓库的人，无论用哪个 Agent，都用同一套指标口径。问过几个
涉及客户、订单、商品的问题之后，插件还会提议一次构建 ontology（Claude Code），之后
就能按业务概念提问。