Doris-Skills：让 AI Agent 真正会用 Apache Doris

叮咚✨欢迎走进「数据极客圈」！专注大数据、AI 技术交流，大咖分享一线经验，持续输出实用技术锦囊。聚集同行伙伴，交流共进，欢迎关注加入！

一、通用 LLM 在 Doris 场景下的局限

做 Doris 开发、运维、AI 数据对接这么久，发现绝大多数人学习资源只有两处：官方文档、零散博客。但是官方文档偏向功能说明，缺少贴合真实业务的落地细节；网上博客内容碎片化，版本不匹配、参数不严谨，线上使用极易踩坑。

所以在实际工作中，越来越多的人借助 Claude、Cursor、Codex 等工具辅助编写 SQL 和 DDL。但一个普遍的体验是：当对话涉及 Doris 特有的设计约束时，通用大模型的输出质量会显著下降。

以建表为例。Doris 的 DUPLICATE、UNIQUE、AGGREGATE 三种数据模型在查询性能上存在明确排序（DUPLICATE > UNIQUE MoW > UNIQUE MoR ≈ AGGREGATE），且数据模型（DUPLICATE/UNIQUE/AGGREGATE）建表后不可切换，需 upfront 选对。通用 LLM 往往能够复述这一概念，但在实际生成 DDL 时，却频繁出现以下问题：

• 在 UNIQUE KEY 表上使用 RANGE 分区时，未将分区列纳入 KEY 定义，导致 DDL 直接被拒绝；
• 将 store_row_column 属性误用于 AGGREGATE 表，而 Doris 对此的报错信息是 "Aggregate table can't support row column"；
• 排序键中把低选择性的 VARCHAR 字段放在高选择性的 BIGINT 之前，破坏了 Prefix Index 的有效性；
• 分桶数写成 AUTO 或拍脑袋给一个数字，导致 tablet 大小偏离 1–10GB 的合理区间；

这些问题并非 LLM 的「幻觉」，而是 Doris 作为一门具有鲜明设计哲学的 OLAP 数据库，其大量约束和最佳实践并未被充分编码到模型的训练语料中。doris-skills 的出现，本质上是在填补这一空白。

二、Doris-Skills 是什么

doris-skills 是 Apache Doris 官方维护的一套 Agent Skills，采用开放的 SKILL.md 格式，将 Doris 的内核知识编码为可供 AI Agent 直接调用的结构化规则。

仓库包含三个技能模块，分别覆盖「表设计 → 架构决策 → 运行时诊断」完整链路：

2.1 doris-best-practices — 表设计与运行时调查

聚焦表设计、容量规划与慢查前置调查。包含 37 条规则、7 个场景化用例模板、4 份容量规划指南，以及 12 类 DDL 硬约束陷阱（schema-ddl-gotchas）。覆盖数据模型选择、分区/分桶、排序键、索引、物化视图、缓存策略等完整设计链路；同时定义「证据优先」的调查流程，指导 Agent 在给出优化建议前先收集 profile、tablet、EXPLAIN 等运行时证据。

2.2 doris-architecture-advisor — 架构层决策

聚焦从零到一的架构设计。提供 8 条决策规则、5 步标准化工作流，以及 10 个来自不同行业的完整架构案例（涵盖 IoT、证券、零售、物流、Web3、支付、游戏、广告等场景）。与 doris-best-practices 配合使用：前者决定 建什么、怎么分层，后者保证产出的 DDL 语法正确、约束合规。

2.3 doris-profile-reader — Profile 解读与瓶颈定位

Profile 是慢查诊断链路的关键入口。当用户提供 Profile 文本、query_id 或性能问题时自动激活，能力包括：

• 区分真实计算 vs 误导性等待：不把 WaitForDependencyTime、WaitForDataN 等排队/背压计数器误判为算子本身的开销；
• 按算子类型优先级读指标：Scan 优先看 RowsRead/ScanBytes/ScannerCpuTime；Join 需先识别 build/probe 侧再判断顺序是否合理；
• Join 顺序与 Runtime Filter 专项分析：区分 RF 的 source/target 方向，避免「RF 生效了所以 Join 顺序没问题」这类常见误判；
• 标准化输出结构：结论 → 证据 → 推理 → 下一步检查，并显式标注 proven / likely / not proven。

它与 doris-best-practices 的分工是：best-practices 规定 先拿证据再下结论，profile-reader 规定拿到 Profile 后怎么读、怎么判。

2.4 与传统文档的区别

Skills 文件中每条规则都带有明确的触发条件、约束说明和决策逻辑。当 Agent 检测到用户正在讨论 Doris 建表、慢查询诊断或架构设计时，对应规则会被自动激活，并引导 Agent 按既定流程执行——而不是依赖模型从训练语料里猜 Doris 的行为。

2.5 质量保障：verify/ 三层回归

这也是 doris-skills 与普通 prompt 包的本质区别：内容不是写死在文档里就完事，而是持续与真实 Doris 集群对齐。

仓库内置 verify/ 回归套件，分三层验证：

这意味着：当 Doris 版本演进、DDL 语法变更或 doriscli 接口调整时，skills 的内容可以通过回归测试发现漂移并及时修正——而不是等用户线上踩坑才发现 Agent 给的建议已经过时。

三、Doris-Skills 能做什么

1. 场景化 DDL 生成

以 CDC 同步场景为例。当用户描述需要从 MySQL 同步订单数据到 Doris 时，Agent 会依次执行以下判断：

• 工作负载含 UPDATE/DELETE，排除 AGGREGATE 模型，选择 UNIQUE MoW；
• 数据量 50GB，低于 100GB 分区阈值，建议不分区；
• 按 50GB × 0.2 压缩率 = 10GB 计算，目标 tablet 2GB，得出 5 个 buckets；
• CDC 事件可能乱序，自动加入 function_column.sequence_col = "update_time"；
• 输出带完整注释的 CREATE TABLE，并标注每条决策所引用的规则编号。

2. 慢查询诊断（多 skill 协作）

传统方式下，AI 看到慢查询往往直接建议加索引。doris-skills 定义了一套分层诊断流程：

第一步 — 证据收集（doris-best-practices / cli-investigation.md）

通过 doriscli profile get <query_id>、doriscli tablet db.table 等命令获取运行时数据；在证据不足时，Agent 只允许输出调查计划，禁止直接给根因和修复方案。

第二步 — Profile 解读（doris-profile-reader）

对拿到的 Profile 按标准化流程分析：先分离 wait 类计数器与真实 ExecTime，再按算子类型定位瓶颈；涉及 Join 时额外判断 build/probe 顺序和 Runtime Filter 方向。

第三步 — 优化建议（回到 doris-best-practices 规则索引）

只有在证据链完整后，才映射到具体规则——例如 tablet_skew > 3 指向 schema-bucket-composite-for-skew，Scan selectivity 过高指向 schema-keys-selectivity-first，spilled_operators > 0 指向内存/Spill 调优。

这种 证据优先 + 专业解读 + 规则映射 的三段式方法论，避免了基于语料的猜测，使诊断结论具备可验证性。

3. DDL 硬约束的规避

Doris 有大量在编译期直接拒绝的 DDL 约束。schema-ddl-gotchas 专门维护 12 类常见错误。Agent 在输出任何 CREATE TABLE 之前，必须逐项检查 Pre-Flight Checklist，例如：

• Key 列是否为 schema 的前 N 列且顺序一致；
• AUTO PARTITION 是否同时包含 date_trunc() 和空括号 ()；
• compaction_policy = "time_series" 是否仅用于 DUPLICATE 表；
• 异步物化视图的刷新语法是否为 REFRESH AUTO ON SCHEDULE EVERY 10 MINUTE 而非其他变体。

这相当于在 Agent 侧实现了一个前置语法校验层，避免了很多基础问题。

4. 容量规划的计算

Skills 中提供了明确的 sizing 公式。以集成存储模式为例：

• BE 节点：16–64 核 CPU，64–256GB 内存，经验法则为每 1TB 存储数据配 4GB RAM；
• 分桶数：daily_data_GB × compression_ratio / target_tablet_GB，目标 tablet 大小控制在 1–10GB 之间；
• 存储估算：原始数据 × 压缩率（通常 0.2–0.3）× 副本数。

Agent 能够根据用户输入的数据量级，自动完成上述计算并给出具体的节点配置建议。

5. 跨 Agent 工具的通用性

doris-skills 采用开放的 SKILL.md 格式，不绑定任何特定 AI 工具。目前支持通过 npx skills add apache/doris-skills 一键安装到 Claude Code、Cursor、Codex、Cline、Amp 等环境中，自动发现仓库中的三个技能模块。这种一次编写，到处运行的设计理念，降低了知识迁移的边际成本。

四、如何接入

目前有三种使用方式：

1. 通过 skills CLI 安装（推荐）：npx skills add apache/doris-skills，自动发现仓库中的三个技能模块及其 references/ 目录；
2. 手动复制到 Agent 目录：将 skills/ 下的文件复制到对应 Agent 的 skills 目录（如 ~/.claude/skills/ 或 ~/.cursor/skills/）；
3. 配合 doriscli 使用：安装 npm install -g @apache-doris/doriscli 后，Agent 可获得结构化的 profile 诊断和 tablet 健康检查能力——这正是 doris-profile-reader 与 doris-best-practices 慢查流程所依赖的「手」。

值得注意的是，即使不安装 doriscli，Skills 也会自动回退到 MySQL 协议 + FE HTTP API 的原生路径，保证基础功能可用。

五、结语

很多人学习 Doris 仍主要依赖官方文档和零散博客。官方文档回答Doris 能做什么，而 doris-skills 更聚焦怎么在真实业务里设计得对、跑得稳、查得准 ——并把这些经验编码成 Agent 可调用的结构化规则。

尤其现在智能数据应用成为标配，把 doris-skills 接入 Claude Code、Cursor 等 Agent 工具，再搭配可选的 doriscli，可以显著降低 DDL 踩坑和慢查误诊的概率，缩短从 会用 Doris 到 用好 Doris 的路径。