Hologres CLI与Skills担当Agent-Ready 基础设施，共建数仓智能新生态-阿里云开发者社区

在 AI Agent 时代，数据仓库不再只是"被查询的对象"，而是 Agent 可以自主操作、理解、优化的智能基础设施。Hologres AI Plugins 让每一位开发者和 AI Agent 都能安全、高效地驾驭 Hologres。

一、AI Agent 时代，数据仓库需要变

过去，我们用 SQL 手动查库、手动调优、手动排障。DBA 是数据仓库的"翻译官"。

但在 AI Agent 时代，范式变了：

Claude Code 在帮你写代码时，需要查看线上表结构；
Cursor 在优化 SQL 时，需要读取执行计划；
OpenAI Codex 在排查慢查询时，需要分析 hg_query_log。

Agent 不会手动打开 DBeaver，也不会去翻运维文档。它需要的是：

Agent 需要什么	传统方式	Agent-Ready 方式
查看表结构	登录控制台，找到数据库	`hologres schema describe orders`
执行 SQL	打开 SQL 编辑器	`hologres sql run "SELECT ..."`
分析执行计划	手工 EXPLAIN	`hologres sql explain "SELECT ..."`
调整参数	ALTER DATABASE 手写	`hologres guc set param value`
创建动态表	拼 DDL	`hologres dt create -t my_dt --freshness "10 min" -q "..."`

Agent 需要"结构化输入、结构化输出、安全护栏"的 CLI，而不是给人看的 GUI。

这就是 Hologres AI Plugins 解决的问题。

二、整体架构：两层设计，让 Agent 从"能用"到"会用"

┌─────────────────────────────────────────────────────────┐
│                   AI Agent / IDE Copilot                 │
│         (Claude Code / Cursor / Codex / Qoder ...)      │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┐
        │                           │
        ▼                           ▼
┌───────────────┐         ┌──────────────────┐
│  Hologres CLI │         │  Agent Skills    │
│ (执行层)       │         │  (知识层)         │
│               │         │                  │
│ • 安全护栏     │         │ • CLI 使用指南    │
│ • JSON 输出   │         │ • 查询优化知识    │
│ • Profile 管理│         │ • 慢查询诊断      │
│ • 审计日志     │         │ • GUC 参数手册    │
└───────┬───────┘         └──────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│         Alibaba Cloud Hologres       │
│    (实时数仓 / HSAP / PostgreSQL兼容) │
└───────────────────────────────────────┘

Hologres CLI（执行层）：Agent 的"双手"，安全地执行数据库操作
Agent Skills（知识层）：Agent 的"大脑"，教会 Agent 如何正确使用 Hologres

三、Hologres CLI：为 Agent 设计的安全命令行

3.1 JSON-First：Agent 天然能理解

所有命令默认返回结构化 JSON：

$ hologres status
{
  "ok": true,
  "data": {
    "connected": true,
    "version": "Hologres 4.1.0",
    "database": "production_db"
  }
}

AI Agent 看到 "ok": true，就知道操作成功；看到 "ok": false，就能根据 error.code 精准定位问题。不需要正则解析，不需要猜测输出格式。

同时支持 4 种输出格式——JSON / Table / CSV / JSONL——满足不同场景需求：

hologres -f json  schema tables    # Agent 消费
hologres -f table schema tables    # 人类阅读
hologres -f csv   schema tables    # 数据导出
hologres -f jsonl schema tables    # 流式处理

3.2 六层安全护栏：让 Agent 不会"闯祸"

在 AI Agent 自主操作数据库时，安全是第一要务。Hologres CLI 内置了六层递进式安全机制，其中前三层构成写操作三层纵深防御体系：

第一层：行数限制保护

# Agent 写了个没有 LIMIT 的 SELECT？自动拦截！
$ hologres sql run "SELECT * FROM orders"
{"ok": false, "error": {"code": "LIMIT_REQUIRED", "message": "Query returns >100 rows, add LIMIT clause"}}

Agent 看到 LIMIT_REQUIRED，自动补上 LIMIT 100 重试。零人工干预。

第二层：连接级只读保护——数据库引擎兜底

Hologres CLI 的所有连接默认只读，创建连接后立即执行：

SET default_transaction_read_only = ON;

这意味着即使 Agent 绕过了 CLI 层面的所有检查，数据库引擎也会拒绝任何写操作。只有当命令明确需要写入时，CLI 才会创建可写连接（read_only=False）。

# 默认只读连接——数据库引擎直接拒绝
$ hologres sql run "INSERT INTO logs VALUES (1, 'test')"
{"ok": false, "error": {"code": "WRITE_GUARD_ERROR"}}
# 即使直接发送 SQL，连接层也会拦截
# 因为连接本身就是 read_only 的

写意图确认方式一览表——只有以下方式才会创建可写连接：

写意图确认方式	命令	连接模式
`--write` 标志	`sql run --write "INSERT ..."`	`read_only=False`
`--confirm` 确认	`dt drop --confirm`, `table drop --confirm`, `table truncate --confirm`, `partition drop --confirm`	`read_only=False`
非 `--dry-run` 执行	`dt create`, `dt alter`, `dt refresh`, `dt convert`, `table create`, `table alter`, `partition alter`	`read_only=False`
命令本身即写意图	`guc set / reset`, `data import`, `extension create`	`read_only=False`
无写意图（默认）	所有查询、所有 list / show / describe 操作	`read_only=True`

三层写保护纵深防御：
  ┌─────────────────────────────────────────────┐
  │  Layer 1: 连接层 (数据库引擎)                 │
  │  SET default_transaction_read_only = ON      │
  │  → 即使所有 CLI 检查被绕过，DB 也拒绝写入      │
  ├─────────────────────────────────────────────┤
  │  Layer 2: CLI 层 (--write 标志)               │
  │  → sql run 必须显式 --write 才允许写操作       │
  ├─────────────────────────────────────────────┤
  │  Layer 3: 安全层 (危险 SQL 检测)              │
  │  → DELETE/UPDATE 无 WHERE 直接阻断           │
  └─────────────────────────────────────────────┘

第三层：写操作显式授权

# 所有 SQL 写操作必须显式加 --write 标志
$ hologres sql run "INSERT INTO logs VALUES (1, 'test')"
{"ok": false, "error": {"code": "WRITE_GUARD_ERROR"}}
# 明确意图后才放行
$ hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"
{"ok": true}

第四层：危险操作阻断

# 没有 WHERE 的 DELETE？直接拦截，不商量
$ hologres sql run --write "DELETE FROM users"
{"ok": false, "error": {"code": "DANGEROUS_WRITE_BLOCKED"}}

第五层：Serverless 计算隔离——Agent 查询不冲击生产

AI Agent 最大的隐患之一：一条未优化的复杂 SQL 可能瞬间打满实例资源，导致线上业务 failover。

Hologres CLI 默认将所有 Agent 发起的 SQL 路由到 Serverless Computing 资源组执行：

# Agent 执行的每条 SQL，底层自动走 Serverless 资源
$ hologres sql run "SELECT region, SUM(amount) FROM orders GROUP BY region LIMIT 100"
# 内部实际执行：SET hg_computing_resource = 'serverless'; SELECT ...

这意味着：

生产实例零冲击：Agent 的查询使用独立的 Serverless 算力池，不占用实例本地资源
弹性伸缩：复杂查询自动获得更多计算资源，无需人工扩容
天然隔离：即使 Agent 连续发起多条重查询，也不会影响在线服务的延迟和稳定性

┌──────────────┐     ┌──────────────────────┐
│  AI Agent    │────▶│  Hologres CLI        │
│  (查询请求)   │     │  routing=serverless  │
└──────────────┘     └──────────┬───────────┘
                               │
                    ┌──────────┴───────────┐
                    │                      │
              ┌─────▼──────┐     ┌────────▼─────────┐
              │ Serverless │     │  Local Instance   │
              │ 算力池      │     │  (在线业务专用)    │
              │ Agent SQL  │     │  不受 Agent 影响   │
              └────────────┘     └──────────────────┘

第六层：Adaptive Execution——复杂 SQL 不会 OOM

Agent 生成的 SQL 复杂度不可预测——可能是简单的 SELECT *，也可能是多表 JOIN + 子查询 + 窗口函数。如果用固定的执行策略，轻则浪费资源，重则内存溢出（OOM）导致查询失败。

Hologres CLI 启用 Adaptive Execution Stage 模式，根据 SQL 复杂度智能选择执行策略：

# 内部自动设置自适应执行
# SET hg_experimental_enable_adaptive_execution = on;

SQL 复杂度	执行策略	效果
简单查询（单表扫描）	单阶段直接执行	低延迟，快速返回
中等查询（JOIN + 聚合）	多阶段流水线	平衡资源与性能
复杂查询（多表 JOIN + 窗口函数）	自适应分阶段	中间结果落盘，避免内存溢出

核心原理：当优化器检测到某个算子的中间结果可能超过内存阈值时，自动将执行计划拆分为多个 Stage，中间结果通过磁盘 Shuffle 交换，用可控的性能代价换取执行的确定性。

Agent SQL ──▶ 优化器评估复杂度
                   │
          ┌────────┴────────┐
          │ 简单SQL          │ 复杂SQL
          ▼                 ▼
     单阶段执行        多阶段自适应执行
     (内存完成)        (中间结果落盘)
          │                 │
          └────────┬────────┘
                   ▼
              安全返回结果
              (永不 OOM)

Serverless + Adaptive Execution 的组合拳，让 Agent 的每一条 SQL 都运行在"安全沙箱"中——既不冲击生产实例，也不会因为内存不足而崩溃。这是传统 CLI 工具不具备的 AI-Native 安全能力。

六层护栏设计的核心理念是：Agent 可以自由探索，但不会意外破坏数据，也不会冲击线上稳定性。连接级只读 + CLI 写守卫 + 危险 SQL 阻断，三层纵深防御让写保护"滴水不漏"。

3.3 敏感数据脱敏：自动保护隐私

当 Agent 查询包含敏感字段的数据时，CLI 自动按列名模式识别并脱敏：

字段模式	原始数据	脱敏后
phone / mobile	13812345678	`138****5678`
email	john@example.com	`j***@example.com`
password / token	mysecret123	`********`
id_card / ssn	110101199001011234	`110***********1234`
bank_card	6222021234567890	`************7890`

Agent 能拿到数据做分析，但不会泄露用户隐私。

3.4 Profile 多环境管理

一条命令切换 dev / staging / prod 环境：

hologres config                      # 交互式配置向导
hologres --profile prod status       # 切换到生产环境
hologres --profile dev schema tables # 开发环境查表

Agent 可以根据上下文自动选择环境，像经验丰富的 DBA 一样在多套环境间切换。

3.5 30+ 命令全覆盖

从日常查询到高级管理，覆盖 Hologres 全部核心场景：

Schema 管理    ─── schema tables / describe / dump / size
Table 管理     ─── table list / create / show / properties / drop / truncate
View 管理      ─── view list / show
SQL 执行       ─── sql run / explain
数据导入导出   ─── data export / import / count
动态表生命周期 ─── dt create / list / show / ddl / lineage / refresh / alter / drop
GUC 参数管理   ─── guc show / set / reset / list
扩展管理       ─── extension list / create
实例信息       ─── instance / warehouse / status

四、Agent Skills：教 AI 成为 Hologres 专家

CLI 解决了"能操作"的问题，但 Agent 还需要"会操作"——知道什么时候用什么命令，知道如何优化查询，知道如何诊断问题。

这就是 Agent Skills 的价值。

4.1 三大技能包

技能一：hologres-cli —— CLI 使用指南

教 Agent 正确使用 30+ 条命令，理解安全机制，处理错误码。Agent 看完这个 Skill，就知道：

查询大表要加 LIMIT
写操作要加 --write
DROP 操作默认是 dry-run，需要 --confirm

技能二：hologres-query-optimizer —— 查询优化专家

把 Hologres 执行计划的解读经验浓缩成 AI 可消费的知识：

Agent 分析流程：
1. 执行 EXPLAIN ANALYZE
2. 看 ADVICE 段获取系统建议
3. 识别瓶颈算子（Seq Scan？Redistribution？）
4. 对症下药（加索引？改分布键？调 GUC？）

Agent 知道 rows=1000 意味着统计信息缺失要跑 ANALYZE；知道 Redistribution 意味着分布键不匹配要调整 distribution_key；知道 ExecuteExternalSQL 意味着走了 PQE 需要改写 SQL。

技能三：hologres-slow-query-analysis —— 慢查询诊断师

基于 hologres.hg_query_log 系统表的诊断工作流：

找出最耗 CPU 的查询模式
定位失败查询的错误根因
分析查询各阶段（优化 / 启动 / 执行）的时间分布
跨时段对比（今天 vs 昨天同时段）

4.2 一键安装，支持 8 大 AI 工具

# 一条命令安装到你的 AI 工具
uvx hologres-agent-skills

交互式安装器支持 8 大主流 AI 开发工具：

选择工具、选择技能包、一键安装。Skills 文件自动复制到对应工具的 skills 目录。

五、动态表全生命周期管理：AI 时代的实时数据编排

Hologres 动态表（Dynamic Table）是实时数仓的核心能力。在 AI Agent 时代，创建动态表不再需要手写复杂的 DDL——用自然语言告诉 Agent 你想要什么，Agent 会自动生成并执行。

用户："帮我基于 orders 表建一个按区域汇总的实时销售看板，5 分钟刷新一次"
Agent 思考链：
  1. hologres schema describe orders → 理解源表结构
     (region VARCHAR, amount DECIMAL, ds DATE, ...)
  2. 根据用户意图，自动生成 CLI 命令：
     hologres dt create -t region_sales_realtime \
       --freshness "5 minutes" \
       --refresh-mode incremental \
       --computing-resource serverless \
       -q "SELECT region, ds,
              SUM(amount) AS total_amount,
              COUNT(*) AS order_count,
              AVG(amount) AS avg_amount
           FROM orders GROUP BY region, ds" \
       --dry-run
  3. 先 --dry-run 预览 SQL → 展示给用户确认
  4. 确认后去掉 --dry-run 正式创建
  5. hologres dt show region_sales_realtime → 确认创建成功

用户全程只说了一句话，Agent 完成了：理解表结构 → 设计聚合逻辑 → 选择刷新策略 → 安全预览 → 执行创建。

创建之后，Agent 同样可以自然语言管理整个生命周期：

# "看看这个动态表的数据来源" → Agent 执行：
hologres dt lineage region_sales_realtime
# "刷新频率改成 1 分钟" → Agent 执行：
hologres dt alter region_sales_realtime --freshness "1 minute"
# "这个表不需要了" → Agent 执行（默认 dry-run，安全优先）：
hologres dt drop region_sales_realtime           # 只预览 SQL
hologres dt drop region_sales_realtime --confirm # 用户确认后真正执行

Agent 可以根据业务需求，自主创建、调整、监控实时数据管道——而用户只需要用自然语言描述需求。

六、GUC 参数管理：数据库调优的"旋钮"

27 个常用 Hologres 参数，分类管理，--help 即查即用：

$ hologres guc --help
Known Hologres GUC Parameters:
  [Auto Analyze]
    hg_enable_start_auto_analyze_worker
        default=on  开启 Auto Analyze (V1.1+)
  [Query Optimization]
    optimizer_join_order
        default=exhaustive  Join 顺序策略 (exhaustive/query/greedy)
  [Timeout & Connection]
    statement_timeout
        default=8h  活跃 Query 超时时间
  ...

# 查看当前值
hologres guc show statement_timeout
# 数据库级持久化设置
hologres guc set statement_timeout '5min'
# 重置为默认值
hologres guc reset statement_timeout
# 查看所有参数当前值
hologres guc list

七、端到端场景：Agent 如何用 Hologres 解决真实问题

场景一：Agent 自动排查线上慢查询

用户："线上数据库有点慢，帮我看看什么情况"
Agent 思考链：
  1. hologres status → 确认连接正常
  2. hologres sql run "SELECT status, duration, query::char(60)
     FROM hologres.hg_query_log
     WHERE query_start >= now() - interval '10 min'
     ORDER BY duration DESC LIMIT 20"
     → 找到 3 条慢查询
  3. hologres sql explain "SELECT ..." → 发现全表扫描
  4. hologres guc show hg_enable_start_auto_analyze_worker → 确认 auto analyze 已开启
  5. 给出建议：添加 clustering_key + 跑 ANALYZE

场景二：Agent 自动创建实时报表

用户："帮我建一个实时区域销售看板，每 5 分钟刷新"
Agent 思考链：
  1. hologres schema describe orders → 确认源表结构
  2. hologres dt create -t region_sales_rt
     --freshness "5 minutes"
     --refresh-mode incremental
     --computing-resource serverless
     -q "SELECT region, ds, SUM(amount) AS total, COUNT(*) AS cnt
         FROM orders GROUP BY region, ds"
     --dry-run → 预览 SQL
  3. 确认无误后去掉 --dry-run 执行
  4. hologres dt show region_sales_rt → 确认创建成功

场景三：Agent 自动优化查询性能

用户："这个 SQL 跑了 30 秒，帮我优化"
Agent 思考链：
  1. hologres sql explain "..." → 读取执行计划
  2. 识别 Redistribution 算子 → 分布键不匹配
  3. hologres table properties orders → 查看当前 distribution_key
  4. 建议修改分布键 或 调整 GUC
  5. hologres guc set optimizer_force_multistage_agg on --scope session
  6. 重新 explain 验证效果

八、为什么选 Hologres + AI Plugins

能力	Hologres AI Plugins	传统 CLI / GUI
AI 可解析	JSON-First，结构化错误码	自由文本，需正则解析
安全机制	五层护栏 + 自动脱敏	依赖人工判断
计算隔离	默认 Serverless，不冲击生产	共享实例资源，存在风险
内存安全	Adaptive Execution，复杂 SQL 不 OOM	固定策略，大查询可能崩溃
知识注入	Agent Skills 自动加载	人工翻文档
工具链	8 大 AI 工具一键集成	手动配置
动态表	完整 V3.1 生命周期	手写 DDL
参数调优	27 个参数分类管理	记忆力 + 文档
审计追踪	全量操作日志	无

九、快速上手

# 1. 安装 CLI
pip install hologres-cli
# 2. 配置连接
hologres config
# 3. 验证连接
hologres status
# 4. 安装 Agent Skills 到你的 AI 工具
uvx hologres-agent-skills
# 5. 开始使用：让 AI Agent 管理你的 Hologres

项目完全开源，欢迎 Star 和贡献：

GitHub: https://github.com/aliyun/hologres-ai-plugins

十、写在最后

AI Agent 时代，数据仓库的价值不在于它存了多少数据，而在于 AI 能多快、多安全、多智能地使用这些数据。

Hologres AI Plugins 做的事情很简单：

让 Hologres 成为 AI Agent 最顺手的数据仓库。

当你的 Agent 需要查数据 —— 它有安全的 CLI；当你的 Agent 需要懂数据库 —— 它有专业的 Skills；当你的 Agent 需要调性能 —— 它有完整的诊断链路。

从 pip install 到 Agent 自主排障，中间只有一个 hologres config 的距离。

这就是 Agent-Ready。

Hologres CLI与Skills担当Agent-Ready 基础设施，共建数仓智能新生态