跳转至

快速上手

十分钟以内,从一个空目录到一套受治理的语义模型,全程只和编程 Agent 对话:一句话装好 Dosi,连接数据库、建模型、提问、看一个数字是怎么算出来的、解释它为什么变了、查明细记录。 不用写 YAML,也不用写 SQL。

下面的耗时是在 Claude Code 里实测的,Agent 通过 dosi 的 MCP 工具回答;实际耗时会随 模型和推理强度设置有出入。Codex 走的是同样的步骤,DeepSeek Harness 也一样,只是通过 dosi 的命令行;这两个 Agent 里没有 Claude Code 专属的 /dosi 和血缘面板。

在 Agent 里安装 Dosi

启动你的编程 Agent(Claude Code、Codex、DeepSeek Harness、Gemini CLI、Cursor 或其他), 对它说:

按照 https://dosi.datus.ai/agent-install.md 安装 Dosi

Agent 会先判断自己是哪种 Agent,再装好 Dosi 插件(没有插件机制的 Agent 则装 skills 和 dosi 程序),最后确认 dosi 能运行。除非某一步失败,它不会问你任何问题。 只有你能做的那一步,它会交给你:在 Claude Code 里是输入 /reload-plugins;在 Codex 和 DeepSeek Harness 里是到 Agent 的插件菜单里完成安装。

也可以自己输入安装命令
/plugin install dosi --marketplace Datus-ai/dosi-plugins

Claude Code 2.1.275 之前的版本,先执行 /plugin marketplace add Datus-ai/dosi-plugins,再执行 /plugin install dosi@dosi-plugins 和 /reload-plugins。

$ codex plugin marketplace add Datus-ai/dosi-plugins
$ codex plugin add dosi@dosi-plugins

在网页界面打开 Plugins → Add plugin,填入 https://github.com/Datus-ai/dosi-plugins,然后重启 DeepSeek Harness。

每个 Agent 都有单独的页面:Claude Code、Codex、 DeepSeek Harness、其他 Agent。

插件第一次运行时会在后台自己下载 dosi。在中国大陆,启动 Agent 之前先设置 DOSI_SOURCE=oss,从镜像下载。另外建议 PATH 上有 duckdb 命令行:Agent 建模时用它看表结构, 并且以只读方式打开文件。

准备数据

示例库里有大约 19 万笔订单,来自 5,000 个客户、500 种商品,时间是 2024 年 1 到 6 月。 把它放进一个新目录,在那里开一个新会话:

$ mkdir dosi-try && cd dosi-try
$ curl -fsSLO https://dosi.datus.ai/orders-200k.duckdb
$ claude

(也可以启动 codex,或者在 DeepSeek Harness 里打开这个目录。)用什么语言提问都行, Agent 会用同样的语言回答。

第 1 步 —— 连接,约 20 秒

帮我连上数据

插件找到 orders-200k.duckdb,在 dosi-connections.yaml 里写一条名为 local 的连接,然后测试连接。不用回答任何问题:本地文件不需要口令。你会看到一行说明 local(DuckDB)已经连上。

如果是你自己的数据,这一步会读取 dbt profiles 或 Cube 的 .env,或者问你数据在哪里, 而且从不在对话里要口令,见让 Agent 来连接。

第 2 步 —— 建语义模型,2–5 分钟

给这些数据建一个语义模型

Agent 边做边说明每一步:

  1. 用 duckdb -readonly 看三张表的字段和行数。如果 Agent 运行前请你确认,允许即可: 这条命令只读文件;
  2. 分层写出 dosi/model.yaml:先是数据集和两条关联,然后是基础指标(全部订单)、 派生指标(只算已完成订单、客单价、取消率),最后是窗口指标(环比、累计、按地区的 排名和占比)。每次保存都会自动校验;
  3. 把指标和直接从表里算出的数字对一遍。

最后它给一段简短的汇报:建了什么、核对了什么、有什么没建,以及哪些取舍值得你复核。 如果它问到业务含义,每个问题都带推荐答案:回答“按推荐的来”,或者自己选。

模型是 Agent 写的,所以指标名、指标数量和没建哪些指标每次都会有出入;一般是三个数据集、 两条关联、二十个左右的指标。

第 3 步 —— 提问,1 分钟以内

各地区每个月的销售额是多少?

回答是一句结论、一张表,加一行注明连接和行数:

月份 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 步 —— 解释变化,约 1 分钟

二季度销售额为什么比一季度低?

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/model.yaml          # 语义模型
dosi-connections.yaml    # 连接配置
orders-200k.duckdb

问过几个涉及客户、订单、商品的问题之后,插件还会提议一次构建 ontology(Claude Code), 之后就能按业务概念提问。

下一步

  • 连接你自己的数据


    在 Snowflake、BigQuery、Postgres、StarRocks 等数据上走同样的步骤:让 Agent 去连接,口令由你自己填。

  • Dosi 插件


    每个 skill 做什么、口令怎样不进入对话、各个 Agent 有什么不同。

  • 更习惯命令行?


    手动安装 dosi,然后跟着命令行教程 自己编译、执行指标查询,不经过 Agent。