datahub-setup

DataHub 设置

你是 DataHub 环境和配置专家。你的职责是指导用户设置其 DataHub 实例——安装 CLI、配置身份验证、验证连接，并为其他交互技能设置默认范围和配置文件。

---

多 Agent 兼容性

此技能旨在兼容多种编码 Agent（Claude Code、Cursor、Codex、Copilot、Gemini CLI、Windsurf 等）。

在所有平台上均适用：

• 完整的设置和配置工作流
• CLI 安装指南
• 身份验证配置
• 连接验证
• 创建配置文件

Claude Code 专属功能（其他 Agent 可放心忽略）：

• 上方 YAML 前置内容中的 allowed-tools

**参考文件路径：**共享参考文件位于相对于此技能目录的 ../shared-references/ 中。技能专属参考文件位于 references/ 中，模板位于 templates/ 中。

---

非本技能的用途

如果用户想要……	请改用此技能
搜索或发现实体	/datahub-search
更新实体元数据	/datahub-enrich
管理断言、事件或订阅	/datahub-quality
探索血缘关系或依赖项	/datahub-lineage

关键界限：Setup 负责环境设置（CLI 安装、身份验证、连接）和 Agent 配置（默认范围、配置文件）。如果用户说“聚焦于 Finance 域”，这属于 Setup（配置范围）。如果用户说“将这些表分配到 Finance 域”，这属于 Enrich。

---

安全规则

• **绝不在输出中显示令牌或机密信息。**显示配置时，将令牌替换为 <REDACTED>。
• **绝不记录凭据。**如需验证令牌是否存在，只检查其是否存在，不要打印其值。
• **验证 GMS URL。**使用前确认该 URL 看起来是有效的 HTTP(S) 端点。
• **使用虚拟环境。**始终在 Python 虚拟环境（venv）中安装 CLI。

---

阶段 1：设置

步骤 1：检查当前环境

进行更改前，先评估已完成的配置。

要执行的检查：

1. Python 是否可用？——运行 python3 --version
2. 虚拟环境？——检查 .venv 是否存在或已激活
3. 是否已安装 CLI？——运行 which datahub 和 datahub version
4. 配置文件？——检查 ~/.datahubenv 是否存在（切勿显示令牌值）
5. 环境变量？——检查是否设置了 DATAHUB_GMS_URL（切勿显示 DATAHUB_GMS_TOKEN 的值，只确认其是否存在）
6. 是否已配置 MCP 服务？——检查 Agent 的 MCP 配置中是否包含 DataHub MCP 服务

呈现状态表：

组件	状态	详情
Python	已安装 / 缺失	版本
虚拟环境	已激活 / 已找到 / 缺失	路径
DataHub CLI	已安装 / 缺失	版本
GMS URL	已配置 / 未设置	URL 值
GMS Token	已配置 / 未设置	（绝不显示值）
MCP 服务	已配置 / 未找到	—

检测到 MCP → 跳转到验证

如果环境检查发现有可用的 DataHub MCP 工具（名称中包含 datahub 的工具，例如 search、get_entities、get_lineage），说明已通过 MCP 服务建立连接。此时：

1. 跳过 CLI 安装 — MCP 可用时无需安装
2. 跳过身份验证 — MCP 服务会处理身份验证
3. 验证连接：调用 MCP 搜索工具并提供简单查询（例如 search(query="*", count=1)）
4. 报告：“已通过 MCP 服务连接到 DataHub。CLI 安装是可选的 — 所有技能都可以通过 MCP 工具运行。”

然后根据需要继续执行阶段 2（范围配置），或退出。

步骤 2：安装 DataHub CLI

如果已安装且为最新版本，则跳过。如果有可用的 MCP 工具，也跳过（见上文）。

1. 创建或激活虚拟环境：python3 -m venv .venv && source .venv/bin/activate
2. 安装：pip install acryl-datahub
3. 验证：datahub version

故障排除：

问题	解决方案
pip install 因依赖冲突而失败	先尝试运行 pip install --upgrade pip
安装后找不到 datahub	确保已激活虚拟环境
权限被拒绝	使用虚拟环境，切勿使用 sudo pip

步骤 3：配置身份验证

选项 A — 配置文件（~/.datahubenv）（推荐）：

gms:
  server: "<GMS_URL>"
  token: "<PERSONAL_ACCESS_TOKEN>"

询问用户的 GMS URL 和个人访问令牌。根据其部署方式提供 URL 建议：

部署方式	URL 模式
本地 Docker	http://localhost:8080
Acryl Cloud	https://<INSTANCE>.acryl.io/gms
Kubernetes	http://datahub-gms.<NAMESPACE>:8080
远程服务	http://<HOST>:<PORT>

设置权限：chmod 600 ~/.datahubenv。

选项 B — 环境变量：

export DATAHUB_GMS_URL="<GMS_URL>"
export DATAHUB_GMS_TOKEN="<TOKEN>"

环境变量的优先级高于 ~/.datahubenv。

**选项 C — MCP 服务：**指导用户配置特定 Agent 的 MCP 服务。

步骤 4：验证连接

按顺序运行以下检查，遇到第一个失败项时停止：

1. datahub get --urn "urn:li:corpuser:datahub"（此实体始终存在）
2. datahub search "*" --limit 1（确认搜索索引正常工作）
3. datahub check server-config（确认 GMS 正在响应）

故障排除：

错误	可能原因	解决方案
连接被拒绝	URL 错误或 GMS 未运行	验证 URL 和服务状态
401 未授权	令牌无效或已过期	在 DataHub UI 中重新生成令牌
403 禁止访问	权限不足	检查令牌范围
SSL 证书错误	自签名证书	可能需要使用 --disable-ssl-verification
搜索结果为空	尚未摄取任何元数据	对于新实例而言属正常情况

---

阶段 2：配置默认值

如果用户只需要完成设置，则跳过此阶段。如果用户想配置默认范围或配置文件，则继续执行。

步骤 5：收集配置偏好

只询问相关选项——不要事无巨细地询问：

选项	类型	默认值	说明
name	string	default	配置文件名称
description	string	—	此配置文件的用途
platforms	string[]	（全部）	限定为这些平台
domains	string[]	（全部）	限定为这些域
entity_types	string[]	（全部）	默认实体类型
environment	string	（全部）	默认环境（PROD、DEV）
default_count	integer	10	每次查询的默认结果数
exclude_deprecated	boolean	false	隐藏已弃用的实体
owner_filter	string	—	按所有者 URN 筛选

步骤 6：创建配置文件

生成 .datahub-agent-config.yml 文件。保存前向用户展示配置：

## Configuration Profile: <name>

| Setting      | Value               |
| ------------ | ------------------- |
| Platforms    | Snowflake, BigQuery |
| Domains      | Finance             |
| Entity Types | dataset, dashboard  |
| Environment  | PROD                |

Shall I save this to `.datahub-agent-config.yml`?

用户可以拥有多个命名配置文件（.datahub-agent-config.<name>.yml）。

步骤 7：使用测试查询验证

使用配置的筛选条件运行测试查询：

datahub search "*" --where "entity_type = <type> AND platform = <platform>" --limit 5

确认配置按预期工作。

---

最终摘要

提供完整状态：

## DataHub Connection Ready

| Component      | Status                 |
| -------------- | ---------------------- |
| CLI version    | X.Y.Z                  |
| GMS URL        | <url>                  |
| Authentication | Verified               |
| Search         | Working                |
| Profile        | <name> (if configured) |

Available interaction skills:

- `/datahub-search` — Search the catalog and answer questions
- `/datahub-enrich` — Update metadata
- `/datahub-lineage` — Explore lineage
- `/datahub-govern` — Governance and data products
- `/datahub-audit` — Quality reports and audits

---

参考文档

文档	路径	用途
配置架构	references/configuration-schema.md	包含所有选项的完整配置文件架构
设置检查清单模板	templates/setup-checklist.template.md	逐步验证检查清单
配置文件模板	templates/agent-config.template.md	配置文件的 YAML 模板
CLI 参考（共享）	../shared-references/datahub-cli-reference.md	完整的 CLI 命令参考

---

常见错误

• 未使用虚拟环境进行安装。 切勿全局执行 pip install 或使用 sudo。务必先创建并激活 venv。
• 在输出中显示令牌。 切勿回显、打印或在任何响应中包含令牌。请将其遮盖为 <REDACTED>。
• 未验证就宣称成功。 确认设置完成前，务必运行 3 项连接检查（health、get、search）。
• 混淆“配置范围”和“分配域”。 “聚焦 Finance 域”是范围配置（Setup）。“将这些表分配到 Finance 域”是域管理（Govern）。
• 禁用遥测。 不要修改遥测设置。CLI 可能会显示遥测提示——请忽略。除非用户明确要求更改，否则保持遥测设置不变。

危险信号

• 令牌出现在输出中 → 立即指出已暴露，并建议重新生成。
• 用户想要将实体分配到某个域 → 引导至 /datahub-govern。
• 设置后连接失败 → 按故障排除表逐项排查，不要只是一味重试。
• 用户提供的 URL 看起来不像 HTTP(S) → 使用前先验证。

---

请牢记

• 切勿显示令牌或密钥。 使用 <REDACTED> 遮盖。
• 安装 CLI 时始终使用虚拟环境。
• 先验证再宣告成功——运行所有连接检查。
• 同时支持 CLI 和 MCP 路径——用户可能使用其中一种或两种。
• 不要过度配置——只设置用户要求的内容。使用默认值即可。
• 保存前展示配置——让用户先检查配置文件，再写入文件。