Skill

NineData-Skill 是面向 AI Agent 和 Vibe Coding 工具的技能能力集合。通过 Skill，AI Agent 可以在 NineData 的身份验证、权限检查、SQL 规则检查、数据掩码、限流、审批和审计日志约束下，调用 NineData 平台能力完成数据源查询、只读 SQL 执行、SQL 任务和数据导出等操作。

功能说明

SQL 执行：用于在具备权限的数据源上下文中执行明确的 SQL，或获取执行计划等信息。
SQL 任务：用于将 SQL 提交到安全审批流程，适合需要规则检查、审批和审计的变更场景。
数据导出：用于将只读查询结果提交为 CSV、Excel、SQL、JSON、XML 或文本文件，并跟进审批、执行、日志和文件状态。
平台能力调用：支持 AI Agent 结合 NineData 的 OpenAPI 调用平台能力，例如列出数据源、检查数据库状态或验证开发数据。
安全管控：Skill 调用会受到 NineData 账号身份、组织权限、SQL 规则、数据掩码、限流和审计日志等机制约束。

Skill 工具

工具入口	用途
`list-datasource`	查询当前 OpenAPI 凭证可访问的数据源。
`sql-execute`	执行只读 DQL 或元数据检查，并返回平台决策和结果预览。
`sql-task`	提交并跟进需要规则检查、审批和执行控制的 SQL 任务。
`data-export`	提交并跟进只读查询结果的数据导出任务。

使用场景

场景	说明
查询可访问数据源	让 Agent 获取当前凭证可访问的数据源列表，辅助选择目标环境。
只读数据查询	在授权范围内执行明确的查询 SQL，并返回结果预览。
SQL 执行计划分析	对待执行 SQL 获取执行计划或诊断信息，辅助评估风险。
SQL 任务提交	对涉及数据或结构变更的 SQL，通过 NineData SQL 任务提交审批流程。
查询结果导出	对只读查询结果创建数据导出任务，并按平台状态处理审批、执行和文件权限。
自动化辅助开发	在 Vibe Coding 或 Agent 工作流中，让 Agent 基于 NineData 权限边界完成数据验证。

注意事项

在让 AI Agent 调用 Skill 前，请先确认目标数据源、SQL 内容和账号权限符合预期。
对于会修改数据或结构的 SQL，建议优先使用 SQL 任务能力提交审批流程。
对于只读查询、执行计划查看或开发数据验证等场景，可根据组织权限和安全规则使用 SQL 执行能力。
对于需要生成文件的只读查询，使用 数据导出能力；导出文件下载和加密密码查看需要单独授权。
Skill 返回的结果可作为 AI Agent 的辅助判断依据，正式执行变更前仍建议结合审批、审计和业务影响进行复核。
不要让 Agent 直接连接数据库，也不要在 Skill 中保存数据库账号密码。
不要在对话、日志或提交记录中暴露 accessKeySecret、Cookie、Token、签名或数据库凭证。
当平台返回拒绝、失败、需要确认、需要 SQL 任务或需要审批时，不要绕过平台裁决重新提交。
approve、reject、transfer-approval 等审批操作属于高风险操作，必须由用户明确指定具体动作后再执行。

警告

不要将 accessKeySecret、Cookie、Token、签名或数据库凭证写入文档、截图、对话记录或代码仓库。配置文件应仅保存在本地 Agent 运行环境，并设置合适的文件权限。导出文件和加密密码也应按敏感数据处理。

前提条件

已登录 NineData 控制台。
当前账号已具备访问 Skill 页面的权限。
已在 NineData 用户管理中为调用账号开启 OpenAPI AccessKey，并保存 AccessKey 和 SecretKey。
如需通过 Skill 执行 SQL 或提交 SQL 任务，当前账号需具备目标数据源和相关 DevOps 流程的操作权限。

页面操作

在 NineData-Skill 页面右上角，可以使用以下操作：

操作	说明
描述	查看 NineData-Skill 的版本、工具 ID、调用方式、OpenAPI 端点、返回字段和使用边界。
下载	下载 `ninedata-skill.zip`。压缩包中包含 Skill 说明、配置示例、客户端安装参考和调用脚本。
快速配置引导	查看 Claude Code、Codex、Cursor、Hermes、OpenClaw、Trae、Qoder、Open Code 等客户端的安装目录和验证提示词。

查看 Skill 能力

登录 NineData 控制台。
在左侧导航栏中，单击 Skill。
在 NineData-Skill 页面查看当前支持的 Skill 能力。
页面会展示 Skill 的用途说明，并以列表形式展示功能名称、功能描述和发布时间。

下载并配置 Skill

在 NineData-Skill 页面右上角，单击下载图标，下载 ninedata-skill.zip。
解压压缩包，得到 ninedata-skill 目录。

将完整的 ninedata-skill 目录复制到目标 AI Agent 客户端的 Skill 目录。

客户端	安装目录示例
Claude Code	`~/.claude/skills/ninedata-skill/`
Codex	`~/.codex/skills/ninedata-skill/`
Cursor	`~/.cursor/skills/ninedata-skill/`
Hermes Agent	`~/.hermes/skills/ninedata-skill/`
OpenClaw	`~/.openclaw/skills/ninedata-skill/`
Trae	`~/.trae/skills/ninedata-skill/`
Qoder	`~/.qoder/skills/ninedata-skill/`
Open Code	`~/.opencode/skills/ninedata-skill/`

复制 config.example.json 为 config.json，然后在 Skill 根目录中编辑配置文件。

{
  "endpoint": "https://your-ninedata-domain.example.com",
  "accessKeyId": "replace-with-access-key-id",
  "accessKeySecret": "replace-with-access-key-secret",
  "defaultDsId": "replace-with-default-datasource-id",
  "defaultDbName": "replace-with-default-database-name",
  "defaultSchemaName": "replace-with-default-schema-name",
  "source": "NINEDATA_SKILL",
  "defaultPageSize": 50,
  "defaultLanguage": "enus"
}

配置项	说明
`endpoint`	NineData 控制台根地址。SaaS 可填写 `https://console.ninedata.cloud`，私有化或专属集群环境请填写实际控制台地址。
`accessKeyId`、`accessKeySecret`	NineData OpenAPI 凭证。在控制台用户管理中开启 AccessKey 后获取，必须保存在本地受限配置中。
`defaultDsId`	默认数据源 ID。查询数据源列表时可不配置；执行 SQL 时如未通过参数指定数据源，则使用该值。
`defaultDbName`	默认数据库名称。
`defaultSchemaName`	默认 Schema 名称。不同数据库类型按需填写。
`source`	调用来源，建议保留 `NINEDATA_SKILL`。
`defaultPageSize`	默认分页大小。
`defaultLanguage`	返回信息语言，例如 `enus`。

设置配置文件权限。Linux/macOS 可执行以下命令；Windows 请在文件属性的安全设置中限制当前用户访问。
```
chmod 600 config.json
```
确认客户端允许执行 Skill 目录下的 scripts/*.sh 脚本，然后重启客户端或开启新的 Agent 会话。

在 Agent 对话中明确要求使用 NineData Skill。

使用 ninedata-skill 查询我可访问的 MySQL 数据源。

验证 Skill 配置

配置完成后，先运行 Skill 自带的配置检查，再查询数据源：

scripts/validate-config.sh
scripts/list-datasource.sh --page-size 5

如果没有在 config.json 中设置默认数据源，可以先使用数据源查询结果选择目标 datasourceId。Skill 支持通过 --config 或 NINEDATA_SKILL_CONFIG 临时指定配置文件。验证请求只返回当前 OpenAPI 凭证可访问的数据源和平台错误信息，不会直接连接数据库。

使用 Skill 查询数据

Skill 配置完成后，您可以在 AI Agent 客户端中用自然语言描述查询需求。例如：

使用 ninedata-skill 查询生产 MySQL 数据源中的订单数量。

Agent 应先识别可访问的数据源，并向您展示将要执行的完整 SQL。确认 SQL 内容、目标数据源和查询目的无误后，再让 Agent 继续提交。sql-execute 仅用于只读 DQL 和元数据检查；会改变数据、结构、权限或事务状态的语句必须进入 SQL 任务。

NineData 会根据平台规则返回执行结果或下一步建议。常见结果包括：

查询已执行，并返回结果预览。
需要再次确认完整 SQL。
当前 SQL 被权限、规则或安全策略拒绝。
当前 SQL 需要通过 SQL 任务或审批流程处理。
数据库执行失败，并返回错误信息和请求 ID。

返回结果说明

返回结果	说明
查询结果预览	NineData 已在权限范围内执行查询，并返回部分结果。
需要确认	Agent 或平台需要您确认目标数据源、SQL 内容或执行影响。
被规则拒绝	SQL 命中权限、数据掩码、SQL 规范或安全策略限制。
需要 SQL 任务	当前 SQL 不适合直接执行，需要提交到 SQL 任务流程。
执行失败	数据库返回错误信息，可结合错误内容继续排查。

常见 SQL 执行决策包括 EXECUTED、REJECTED、NEED_CONFIRMATION、NEED_SQL_TASK 和 FAILED。结果预览可能受分页或平台保护策略限制，请结合返回的截断状态判断结果是否完整。

使用 Skill 提交 SQL 变更

如果需要执行会修改数据、结构、权限或事务状态的 SQL，例如 INSERT、UPDATE、DELETE、CREATE、ALTER、DROP、GRANT、REVOKE、事务控制语句或可能改变状态的存储过程调用，Agent 应通过 NineData SQL 任务提交。混合 SQL 批次中只要包含一条非只读语句，也应进入 SQL 任务。

典型流程如下：

在 AI Agent 客户端中描述变更需求。

使用 ninedata-skill 为测试库提交一条 SQL 任务，给 orders 表新增 remark 字段。

Agent 展示目标数据源、数据库、完整 SQL 和可选回滚 SQL。
确认内容无误后，明确同意提交 SQL 任务。
NineData 创建 SQL 任务并返回任务 ID、规则检查结果、审批状态和控制台任务链接。
根据任务状态继续提交审批、等待审批或执行任务。多级审批场景需要逐个处理当前审批节点，只有详情返回 canExecute=true 后才能执行。

对于审批、执行、暂停、恢复、终止、取消、驳回、转交审批等操作，Agent 应先展示当前任务状态和操作影响，并在获得您的明确确认后再继续。

使用 Skill 导出查询结果

数据导出用于将只读查询结果生成文件。支持 csv、excel、sql、json、xml 和 txt 文件类型。导出任务仍需遵循规则检查、审批、执行权限和审计流程。

确认数据源、数据库、Schema 和完整的只读 SQL。
使用 data-export 提交导出任务，并指定文件类型、字符集和导出内容等选项。
查询任务详情，确认规则检查、审批状态、执行状态和 fileAvailable。
需要审批时，按平台返回的当前审批节点提交审批；多级审批需要逐节点确认。
仅在 canExecute=true 且用户明确授权后执行导出任务。
使用导出日志或流程日志排查执行状态。
仅在详情返回 fileAvailable=true 且用户明确请求时获取下载链接；加密密码需要单独授权。

提交、更新、审批、执行、暂停、恢复、停止、取消、跳过、下载和密码查看分别对应不同的状态操作。Skill 不会自动批准、下载文件、返回加密密码或跳过导出任务。

使用建议

首次配置后，先让 Agent 查询可访问的数据源，确认凭证、端点和权限配置正确。
对查询类请求，请要求 Agent 展示完整 SQL、目标数据源和返回范围后再执行。
对变更类请求，请优先使用 SQL 任务，保留规则检查、审批、执行和审计链路。
对导出类请求，请先确认 SQL 和文件范围，再按数据导出任务状态处理审批、执行和下载权限。
对生产环境操作，请让 Agent 先说明影响范围、回滚思路和需要确认的风险点。
如果 Agent 返回平台拒绝或需要审批，请按 NineData 返回结果处理，不要绕过平台安全策略。

Skill

功能说明​

Skill 工具​

使用场景​

注意事项​

前提条件​

页面操作​

查看 Skill 能力​

下载并配置 Skill​

验证 Skill 配置​

使用 Skill 查询数据​

返回结果说明​

使用 Skill 提交 SQL 变更​

使用 Skill 导出查询结果​

使用建议​

相关文档​