Dosi 插件¶
在编程 Agent 里用 Dosi，最快的方式是装插件。装一次，Agent 就有了 dosi 本身、一组 skill（知道怎么连接数仓、建语义模型、通过模型回答问题），还有一组钩子，保证你的口令 不会进入对话。在 Claude Code 和 Codex 里，插件还会在每个会话里启动 dosi 的 MCP 服务。不用另外启动什么，也不用写配置：装好插件，打开项目， 直接问数据问题。
选择你的 Agent¶
-
完整的插件：MCP 工具、skill、钩子，还有状态栏、
/dosi和血缘面板。 -
MCP 工具、skill 和钩子。
-
skill 和钩子，dosi 通过命令行运行。
-
Gemini CLI、Cursor、OpenCode 等：对 Agent 说一句话，就装好 skill 和 dosi。
第一次使用时会发生什么¶
第一次开会话时，插件在后台把最新版 dosi 下载到它自己的数据目录（大约十秒）。
它不会动你自己装的 dosi，也不会运行低于它所需版本的 dosi。在中国大陆，设置
DOSI_SOURCE=oss 就从国内镜像下载。
之后一直用这个版本，直到你要求更新。在对话里说“升级 dosi”（或者问现在是什么版本）， Agent 就会检查并安装新版本。插件每天也会检查一次，有新版本时在某次回答末尾提一句。
Agent 能做什么¶
| Skill | 什么时候用 |
|---|---|
dosi-connect |
你要连接数据，或者还没连接就问了数据问题。它用 dosi migrate conf 读取 dbt profiles 或 Cube 的 .env，本地文件直接连接，数仓则按模板写一条连接 |
dosi-model |
你要建语义模型、加指标或改指标。它用你自己的数据库客户端看表结构，写出 dosi/model.yaml 并完成校验 |
dosi-query |
所有数据问题：数字、趋势、拆分、排名、明细记录、指标为什么变了 |
dosi-view |
“这个数怎么算的”“这个数从哪来”、血缘图 |
dosi-ontology |
你问到业务概念，或者接受了插件构建 ontology 的提议 |
dosi-upgrade |
“dosi 是什么版本”“升级 dosi” |
答案都来自模型里的指标，由 dosi 计算：模型覆盖的表，Agent 不会自己手写 SQL 去查。 你要看生成的 SQL 时，它会给出来。有 dosi 的 MCP 工具时 Agent 调用工具，没有时 通过 dosi 命令行做同样的事。
建模 skill 还带两个辅助命令。dosi-reconcile 把指标和参考数字逐格核对（参考数字来自
你已经信任的报表，用你自己的客户端读出）。dosi-fill-derived 按 dosi 自己的计算写回
派生指标的展开式，不用手写。
口令不会进入对话¶
插件的设计保证口令不经过模型：
- Agent 不会打开
dosi-connections.yaml、dbt 的profiles.yml、.env、secrets.env或数据库客户端的配置，只检查它们在不在，由 dosi 去读。在 Claude Code、 Codex 和 DeepSeek Harness 里，钩子会直接拦下这类读取。 - 数仓需要口令时，Agent 写一个
${NAME}占位符，请你自己填：在dosi-connections.yaml里替换掉它（这个文件不进 git），或者把NAME=...写进~/.config/dosi/secrets.env。下一次调用就生效，不用重启。 - 建模时要看表和字段，Agent 用你已经配好、能自动登录的数据库客户端（MySQL 的 login path、Postgres 的 service、SnowSQL 的 connection）。命令行里不带口令，也不会自己 安装客户端。
不同 Agent 的差别¶
| Claude Code | Codex | DeepSeek Harness | |
|---|---|---|---|
| dosi 的 MCP 工具 | 有 | 有 | 没有，skill 走命令行 |
| 拦截读取连接配置 | 有 | 有 | 有 |
| 每次改模型后自动校验 | 有 | 有 | 有 |
| dosi 自己的调用不弹权限确认 | 有 | 按 Codex 自己的规则 | 按 DeepSeek Harness 自己的规则 |
状态栏、/dosi 和血缘面板 |
有 | 没有 | 没有 |
| 功能建议（血缘、ontology） | 有 | 没有 | 没有 |
项目里会生成的文件¶
dosi/model.yaml # 语义模型：请提交
dosi/ontology.yaml # 构建 ontology 后才有：请提交
dosi/mapping.yaml # ontology 到模型的映射：请提交
dosi-connections.yaml # 连接配置，可能含口令，已加入 .gitignore
草稿文件（参考数字、试算用的模型副本）放在 dosi/build/ 下。
排错¶
| 现象 | 解决办法 |
|---|---|
dosi_installing |
第一次下载还没完成。等几秒，Agent 会自己重试 |
受限网络下出现 install_failed |
设置 DOSI_SOURCE=oss（国内镜像），然后开新会话 |
| Agent 在 shell 里跑 dosi，没用 MCP 工具 | MCP 服务没启动，或者这个 Agent 本来就没有（DeepSeek Harness）。看对应 Agent 的页面 |
| 升级后查询工具还在用旧版 dosi | 开一个新会话，MCP 服务会用新版本重新启动 |