介绍¶
Datus 是面向现代数据栈的开源数据工程 Agent：用一个 Agent 连接数据仓库、数据目录、语义层和 BI，底座是一套沉淀在团队自己手里的可演进上下文引擎(evolvable context engine)。
Datus 可以完成 SQL 编写与验证、语义模型与指标构建，以及数据管道、报告和看板的生成；每一次执行与修正都会沉淀为上下文，持续提升后续输出的准确性。整个体系在生态上保持开放与灵活：数据库、BI、调度、LLM 乃至团队自己的工具，都能以标准方式接入。
架构¶
整体架构自上而下分三段：谁在用、Agent 由什么组成、连接哪些系统，与上图对应：
- 按角色划分的三个入口：数据工程师在 Datus-CLI 里探索数据、构建资产；分析师通过 Datus-Chat(Web、Slack/飞书、VS Code)提问，使用中的反馈会回流进 Agent；其他 Agent 和应用经 Datus-API(REST、MCP)消费。
- Agent 核心：Subagent 为单个业务域打包配好的上下文、工具和规则，Skill 提供打包的扩展工具；底座是上下文引擎：元数据、指标、参考 SQL、知识与本地文件，检索用业务域树加向量召回，存储默认内嵌 LanceDB 和 SQLite，团队共享上下文时可换 PostgreSQL。
- 连接的系统：LLM、数据仓库、Dosi 语义层、作业调度、BI 工具与 MCP 服务端/客户端，经适配器接入；Plugin 则把第三方平台和公司内部工具接进 Agent。
核心能力¶
准确率来自两处：语义层把业务口径变成可执行的定义，上下文引擎把使用中产生的知识留存下来。Subagent 负责把这些资产交付给使用的人，Plugin 生态与治理让整套体系能接入现有技术栈，并在生产环境中受控运行。
语义建模自动化¶
Agent 读取数据库 schema 和历史 SQL，自动生成 OSI 格式的语义模型与指标定义，校验通过后注册进语义层，不需要手写 YAML。
执行由 Dosi 引擎承担：同一份语义模型编译成 13+ 种数据库方言的 SQL。它是一个独立程序，也可以单独以 CLI、REST 服务或 MCP server 的方式部署，详见 Dosi 语义适配器。
指标问答与归因¶
AskMetrics 依据指标定义回答业务问题，而不是临时拼 SQL；指标出现波动时，attribution_analyze 给出各维度贡献的量化归因。
越用越准的上下文引擎¶
上下文引擎汇集 schema 元数据、参考 SQL 和业务规则，按业务域树组织，配合向量检索召回。使用中的每次修正都会写回知识库，让后续回答持续变准。
Subagent 交付¶
为一个业务领域配好上下文、工具和规则，打包成专属聊天机器人，交付给分析师直接使用。
- 分析师在浏览器、Slack/飞书或 IDE 里提问，报告和看板在对话里生成，本地即可预览，不依赖任何 SaaS 后端。
- 内置 subagent 还覆盖跨库迁移、ETL 作业生成和宽表构建等工程任务，可编排 Airflow 调度。
Plugin 生态与治理¶
- Plugin 框架把第三方平台和公司内部工具接入 Agent：一份
datus-plugin.yml清单声明 CLI 命令、Skill 和 prompt 上下文，按项目启用。 - 适配器覆盖 15 种数据库和 10+ LLM 提供商，另有 MCP 服务端与客户端；Skill 遵循 agentskills.io 约定，支持从 marketplace 安装。
- 治理上，权限分级，SQL 按语句类型授权并由 AI 预审，bash 运行在 OS 级沙箱中，trace 可导出到任意 OTLP 平台。
工作方式¶
Agent 回答的质量，取决于它拿到的上下文质量。Datus 因此把重点放在上下文的沉淀与复用上，下图是完整的循环：
图分前后两半。前半段是数据工程师的工作：探索数据、构建上下文、完成语义建模，产出可复用的资产；后半段是组织对资产的消费：subagent 把它们变成任何人都能提问的服务。
两半之间也不是单向交付：分析师的每次修正都会回流，资产随使用不断变厚。
- 探索：不需要任何前置建设，在 CLI 里直接与数据库对话，用
@table引用表、@file引用文件，边问边熟悉数据。 - 构建上下文：
/init扫描当前项目，/bootstrap和/build-kb把散落在 schema、历史 SQL 和文档里的知识收进知识库；这是后面一切准确性的原料。 - 语义建模：语义建模 subagent 从 schema 和历史 SQL 中挖掘数据集、语义模型与指标，校验后注册进语义层；业务口径从此有了唯一的、可执行的定义。
- 创建 Subagent：用
/agent把配好的上下文、工具和规则打包成面向单个业务域的 subagent；资产从这一步开始变成别人可以直接使用的服务。 - 交付：分析师在自己习惯的地方提问，浏览器、Slack/飞书或 IDE 都可以(见接入方式)；AskMetrics 依据指标定义回答，报告和看板在对话里直接生成。
- 度量：用 benchmark 在 BIRD、Spider 2.0-Snow 或自定义数据集上度量 SQL 准确率，把上下文带来的提升变成可量化的数字。
第 5 步产生的修正、反馈和成功案例会回流进第 2 步的上下文。资产在使用中越来越完整，而不是建成之日就开始过时。
快速开始¶
第一次运行不需要准备自己的数据库：安装自带 California Schools 示例数据集，数据源 california_schools 已预注册。Linux 或 macOS：
打开新终端，运行 datus，然后：
/model配置模型/datasource添加自己的数据源(只用内置示例可跳过)/init(可选)扫描当前项目
也可以用 pip install datus-agent 手动安装(Python 3.12+)。配置分两级：全局 agent.yml 存放主配置，项目下的 .datus/config.yml 保存当前模型、默认数据源等项目级覆盖，详见配置文档。
先完成安装并完成第一次提问，再通过选择上手路径找到符合目标的场景教程：
继续深入
如果要构建可复用上下文，请阅读构建上下文增强 Agent；如果要从源数据创建管道和 Dashboard，请阅读端到端数据工程；如果已有 Dashboard，请阅读将 Dashboard 变成 Copilot。
接入方式¶
六个入口共享同一个 Agent 后端和同一份上下文：在 CLI 里沉淀的资产，分析师在浏览器或 Slack 里提问时同样生效。表中的 demo 是示例数据源名，适用于带 --datasource 参数的命令，请先用 /datasource 创建；使用内置示例时，把 demo 换成 california_schools 即可。
| 接入方式 | 命令 | 适用场景 |
|---|---|---|
| CLI(交互式 REPL) | datus --datasource demo |
数据工程师探索数据、构建上下文、创建 subagent |
| Web 聊天(FastAPI + React) | datus --web --datasource demo |
分析师通过浏览器与 subagent 对话(http://localhost:8501) |
| REST API(FastAPI) | datus-api --datasource demo |
应用通过 REST 消费数据服务(http://localhost:8000) |
| MCP 服务端 | datus-mcp --datasource demo |
MCP 客户端(Claude Desktop、Cursor 等) |
| IM 网关 | datus-gateway |
分析师在 Slack 或飞书中与 subagent 对话 |
| VS Code(Datus Studio) | 连接 datus --web |
IDE 内的目录浏览器、聊天面板、SQL 结果与 AI 图表 |
Print 模式
Print 模式向 stdout 流式输出 JSON，适合脚本与 CI：datus -p "你的问题" --datasource demo。
深入了解¶
-
语义层
语义模型与指标如何生成、存储，并由 Dosi 引擎执行。
-
Subagent
为一个业务领域打包上下文、工具和规则，交付给分析师直接使用的聊天机器人。
-
知识库
上下文引擎的存储：元数据、语义模型、指标、参考 SQL 与记忆。
-
Plugin
通过一份清单把第三方平台和公司内部工具接入 Agent。
-
CLI
交互式 REPL：对话、上下文与执行命令、MCP 扩展和 Plan 模式。
-
Skill
内置与可安装的 Skill：项目初始化、知识抽取、记忆整理等。
-
配置
数据源、模型、语义层、SQL 策略、存储，以及
agent.yml里的其他设置。 -
Benchmark
在 BIRD、Spider 2.0-Snow 或自定义数据集上度量 SQL 准确率。