30 分钟企业工作坊：数据分析

本工作坊是 demos/enterprise/02_snippets_and_predicates.py 与 03_agent_analysis_session.py 的文档转录。实时 LLM 分析为可选项（HVNB_RUN_LLM_DEMO=1）。

你将注册只读 SQL snippet 与 predicate，通过 database MCP profile 执行它们，并模拟 Agent 分析会话。MCP 工具调用日志已在文档中说明，但当前发布基线上尚未交付。

1. 前置条件

完成数据连接，或确保 demos/data/warehouse.db 已存在：

rtk bash scripts/sync-env.bash -- --extra sql
rtk uv run python demos/enterprise/01_connect_and_ingest.py

2. 注册 Snippet 与 Predicate

脚本： demos/enterprise/02_snippets_and_predicates.py 将只读 SQL 存储为 db-snippet 行，将可复用过滤器存储为 db-predicate 行：

import heavenbase as hb
import heavenbase.ext as hb_ext

ws = hb.HeavenBase("ent-02-snippets", backends={"main": {"type": "inmem"}})
ws.enable_extension("database")
database_id = hb_ext.ingest_database(ws, "demos/data/warehouse.db", name="warehouse")["database"][0]

ws.upsert(
    "db-snippet",
    {
        "object_id": "snippet-customer-count",
        "database_id": database_id,
        "title": "Count customers",
        "sql": "SELECT COUNT(*) AS n FROM customers",
        "readonly": True,
        "card_text": "count all customers in warehouse",
    },
)

ws.upsert(
    "db-predicate",
    {
        "object_id": "pred-high-spend",
        "column_id": amount_col_id,
        "expression": "amount > :threshold",
        "desc": "Orders above a spend threshold",
        "card_text": "high spend orders filter",
    },
)

3. 通过 Database Profile 运行 Snippet

database profile 扩展 read/query 工具组，并新增 run_snippet 与 suggest_sql。首次使用时会自动启用扩展：

toolkit = ws.to_mcp(profile="database")

result = toolkit.run("run_snippet", snippet_id="snippet-customer-count")
print(result["rows"])  # [{"n": ...}]

suggestions = toolkit.run("suggest_sql", question="count customers")
print([row["object_id"] for row in suggestions["snippets"]])

除非在 CM_HVNB 中设置 heavenbase.database.allow_write=true（默认 false），否则写 snippet 会被拒绝。

rtk uv run python demos/enterprise/02_snippets_and_predicates.py

4. Agent 分析会话

脚本： demos/enterprise/03_agent_analysis_session.py 暴露 database profile，并在进程内模拟 Agent 调用：

ws.enable_extension("agent")
toolkit = ws.to_mcp(name="ent-03-database", profile="database")

suggested = toolkit.run("suggest_sql", question="count customers")
counted = toolkit.run("run_snippet", snippet_id="snippet-customer-count")
tables = toolkit.run("query", entity="db-table", spec={"select": ["table_name"], "limit": 5})

供外部 Agent 连接：

hb mcp serve --workspace ent-03-analysis --profile database

可选的实时 LLM 分析（需要 provider 凭证）：

HVNB_RUN_LLM_DEMO=1 rtk uv run python demos/enterprise/03_agent_analysis_session.py

该脚本使用 deepseek-v4-flash，并将 database MCP 工具集 (Toolkit) 挂载到 LLMSession。

5. 会话日志（规划中）

通过 heavenbase.mcp.log_sessions 记录 MCP 工具调用已在原型计划中定义，但当前发布基线上尚未实现。CLI 通过 hb llm chat 与 hb llm session 记录日志的功能现已交付。 MCP 日志落地后，enterprise 演示 03 将记录三条针对 agent-message 行的元分析查询：

工具调用频率 — 按 tool_name 分组
错误率 — 筛选 error_flag 为 true 的行
慢调用 — 按 duration_ms 降序排序

Summary

只读 db-snippet 行可通过 database profile 安全执行；写访问默认关闭。
suggest_sql 按卡片文本搜索 snippet 与 predicate，无需在引擎内调用 LLM。
Agent 通过 MCP 连接，获得面向 db-* 实体的小型、schema 感知工具面。

进一步探索

相关资源：

数据连接 — 摄取并浏览 schema 实体
MCP 工具集参考 — Profile 与工具表
Agent 扩展 — 会话、Skill 与 CLI 日志
Enterprise 演示轨道 — 完整可运行脚本

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

30 分钟企业工作坊：数据分析

1. 前置条件

2. 注册 Snippet 与 Predicate

3. 通过 Database Profile 运行 Snippet

4. Agent 分析会话

5. 会话日志（规划中）

Summary

进一步探索

​1. 前置条件

​2. 注册 Snippet 与 Predicate

​3. 通过 Database Profile 运行 Snippet

​4. Agent 分析会话

​5. 会话日志（规划中）

​Summary

​进一步探索

1. 前置条件

2. 注册 Snippet 与 Predicate

3. 通过 Database Profile 运行 Snippet

4. Agent 分析会话

5. 会话日志（规划中）

Summary

进一步探索