Skill
NineData-Skill 是面向 AI Agent 和 Vibe Coding 工具的技能能力集合。通过 Skill,AI Agent 可以在 NineData 的身份验证、权限检查、SQL 规则检查、数据掩码、限流、审批和审计日志约束下,调用 NineData 平台能力完成数据源查询、只读 SQL 执行、SQL 任务、数据导入和数据导出,并提交结构设计与发布任务。
功能说明
- SQL 执行:用于在具备权限的数据源上下文中执行明确的 SQL,或获取执行计划等信息。
- SQL 任务:用于将 SQL 提交到安全审批流程,适合需要规则检查、审批和审计的变更场景。
- 数据导出:用于将只读查询结果提交为 CSV、Excel、SQL、JSON、XML 或文本文件,并跟进审批、执行、日志和文件状态。
- 数据导入:通过
data-import上传本地 SQL、CSV、Excel、JSON、JSONL 或 NDJSON 文件并提交导入任务;可检查文件状态和敏感数据,并跟进审批、执行、详情和导入过程日志。 - 结构设计与发布:通过 NineData-Skill 提交结构设计与发布任务,推进多环境数据库变更。适用范围和操作流程请参见结构设计与发布。
- 平台能力调用:支持 AI Agent 结合 NineData 的 OpenAPI 调用平台能力,例如列出当前账号有权限访问的数据源、检查数据库状态或验证开发数据。数据源列表接口说明请参见获取数据源列表。
- 安全管控:Skill 调用会受到 NineData 账号身份、组织权限、SQL 规则、数据掩码、限流和审计日志等机制约束。
Skill 工具
| 工具入口 | 用途 |
|---|---|
sql-execute | 执行只读 DQL 或元数据检查,并返回平台决策和结果预览。 |
sql-task | 提交并跟进需要规则检查、审批和执行控制的 SQL 任务。 |
data-export | 提交并跟进只读查询结果的数据导出任务。 |
data-import | 上传本地数据文件并提交导入任务;检查文件状态、敏感数据、审批和执行状态及过程日志。 |
使用场景
| 场景 | 说明 |
|---|---|
| 查询可访问数据源 | 让 Agent 获取当前凭证有权限访问的数据源列表,辅助选择目标环境。也可通过获取数据源列表 OpenAPI调用。 |
| 只读数据查询 | 在授权范围内执行明确的查询 SQL,并返回结果预览。 |
| SQL 执行计划分析 | 对待执行 SQL 获取执行计划或诊断信息,辅助评估风险。 |
| SQL 任务提交 | 对涉及数据或结构变更的 SQL,通过 NineData SQL 任务提交审批流程。 |
| 查询结果导出 | 对只读查询结果创建数据导出任务,并按平台状态处理审批、执行和文件权限。 |
| 数据导入 | 在权限和审批约束下,将数据文件导入目标数据源并跟进任务状态。 |
| 结构设计与发布 | 在多环境数据库研发流程中提交结构设计与发布任务;适用范围和操作步骤请参见结构设计与发布。 |
| 自动化辅助开发 | 在 Vibe Coding 或 Agent 工作流中,让 Agent 基于 NineData 权限边界完成数据验证。 |
注意事项
- 在让 AI Agent 调用 Skill 前,请先确认目标数据源、SQL 内容和账号权限符合预期。
- 对于会修改数据或结构的 SQL,建议优先使用 SQL 任务能力提交审批流程。
- 对于只读查询、执行计划查看或开发数据验证等场景,可根据组织权限和安全规则使用 SQL 执行能力。
- 对于需要生成文件的只读查询,使用 数据导出能力;导出文件下载和加密密码查看需要单独授权。
- 数据导入应先上传本地文件并确认文件可用,再提交导入任务;上传成功不代表数据已导入。遇到敏感数据检查告警时,应由用户明确确认,不能让 Agent 自动关闭检查。
- Skill 返回的结果可作为 AI Agent 的辅助判断依据,正式执行变更前仍建议结合审批、审计和业务影响进行复核。
- 不要让 Agent 直接连接数据库,也不要在 Skill 中保存数据库账号密码。
- 不要在对话、日志或提交记录中暴露
accessKeySecret、Cookie、Token、签名或数据库凭证。 - 当平台返回拒绝、失败、需要确认、需要 SQL 任务或需要审批时,不要绕过平台裁决重新提交。
approve、reject、transfer-approval等审批操作属于高风险操作,必须由用户明确指定具体动作后再执行。
不要将 accessKeySecret、Cookie、Token、签名或数据库凭证写入文档、截图、对话记录或代码仓库。配置文件应仅保存在本地 Agent 运行环境,并设置合适的文件权限。导出文件和加密密码也应按敏感数据处理。
前提条件
- 已登录 NineData 控制台。
- 当前账号已具备访问 Skill 页面的权限。
- 已在 NineData 控制台的账户管理 > AccessKey 管理中为调用场景创建 AccessKey,并在创建结果页保存 AccessKey 和 SecretKey。详细步骤请参见管理 AccessKey。
- 如需通过 Skill 执行 SQL 或提交 SQL 任务,当前账号需具备目标数据源和相关 DevOps 流程的操作权限。
页面操作
在 NineData-Skill 页面右上角,可以使用以下操作:
| 操作 | 说明 |
|---|---|
| 描述 | 查看 NineData-Skill 的版本、支持能力、主要返回信息和使用边界。 |
| 下载 | 下载 ninedata-skill.zip。 |
| 快速配置引导 | 查看 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 安装到对应目录。安装目录示例如下:
客户端 安装目录示例 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/按客户端引导完成配置、必要的本地命令权限设置和客户端重启等操作。OpenAPI 凭证仅保存在受限的本地配置中。
在 Agent 对话中明确要求使用 NineData Skill。
使用 ninedata-skill 查询我可访问的 MySQL 数据源。
验证 Skill 配置
配置完成后,在 Agent 对话中要求 NineData-Skill 列出当前账号可访问的数据源,确认 Skill 能按平台权限返回数据源信息。该能力通过 NineData 平台完成,不会让 Agent 直接连接数据库。
使用 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 导入数据
数据导入会向目标数据库写入数据,仍需遵循 NineData 的权限检查、开发规范、审批、执行控制和审计流程。
- 准备待导入文件,并根据数据导入确认目标数据源支持的导入类型和文件格式。
- 在 AI Agent 客户端中说明目标数据源、数据库、Schema、表、文件和导入目的。Agent 应先上传本地文件,并确认文件状态为可用后再提交任务;上传成功不代表数据已导入。
- Agent 应展示目标位置、文件信息和导入选项。确认导入范围、数据覆盖风险和回滚或清理方案后,明确同意提交数据导入任务。若平台提示敏感数据,须由您明确确认;Agent 不得自动关闭敏感数据检查。
- NineData 创建任务后,Agent 应返回任务 ID、规则检查结果、审批状态、执行状态和控制台任务链接。
- 需要审批时,按平台返回的当前审批节点逐级处理;仅在任务允许执行且您明确授权后执行导入。
- 导入完成后,检查任务日志、影响范围和目标表数据;失败时根据任务错误处理,不要绕过平台规则重复提交。
文件上传结果包含文件 ID 和文件可用状态;导入任务结果包含任务 ID、目标数据源和表、导入设置以及审批与执行状态。返回信息中的 log 表示工作流操作历史,process-log 表示导入任务的执行过程日志。
Skill 不会自动批准或执行数据导入任务。生产数据导入前,请确认备份、审批、回滚和测试数据清理要求。
使用 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 返回结果处理,不要绕过平台安全策略。