> 功能说明: 本技能涵盖 自动化配置和灵活的参数设置、多种应用场景、多种配置选项、时使用 等核心能力。

文档数据库云管理平台

通过API浏览和调用文档数据库云管理平台的管理接口.

请求格式

依赖与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

能力矩阵

1. API目录浏览

通过 atlas-api.mjs catalog 列出所有可用的API分类和端点，覆盖50+分类，包括集群管理、数据库用户、网络配置、备份恢复、监控告警等.

node （请参考skill目录中的脚本文件） catalog

2. 端点详情获取

通过 atlas-api.mjs detail 查看特定端点的详细信息，包括HTTP方法、路径参数、请求体Schema和响应格式.

node （请参考skill目录中的脚本文件） detail --category "Clusters" --endpoint "Create Cluster"
```- 验证返回数据的完整性和格式正确性
### 3. Schema定义查询
查看API端点的请求和响应Schema定义，了解参数类型、是否必填和默认值.
```bash
node （请参考skill目录中的脚本文件） detail --category "Database Users" --endpoint "Create Database User" --schema
```- 验证返回数据的完整性和格式正确性
### 4. 实时API调用
通过 `atlas-call.mjs` 直接调用API端点，支持 `--dry-run` 预检和 `--yes` 自动确认.
```bash
# 预检模式（不实际执行）
node （请参考skill目录中的脚本文件） --category "Clusters" --endpoint "Create Cluster" --dry-run --data '{"name":"myCluster", "providerSettings": {"providerName": "AWS", "regionName": "US_EAST_1", "instanceSizeName": "M10"}}'
# ...
# 实际执行
node （请参考skill目录中的脚本文件） --category "Clusters" --endpoint "Create Cluster" --yes --data '{"name":"myCluster", "providerSettings": {"providerName": "AWS", "regionName": "US_EAST_1", "instanceSizeName": "M10"}}'

5. 分类搜索

按关键词搜索API分类，快速定位需要的端点.

node （请参考skill目录中的脚本文件） catalog --search "backup"

6. 凭证管理

通过环境变量管理API凭证，支持公密钥认证方式.

export ATLAS_CLIENT_ID="your_client_id"
export ATLAS_CLIENT_SECRET="your_client_secret"

实操说明

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

> 详细的输入输出格式请参考下方章节说明。

真实示例

示例1：列出所有API分类

node （请参考skill目录中的脚本文件） catalog

输出：

Available API Categories (52):
  - Alerts
  - Atlas Search
  - Auditing
  - Backup
  - Clusters
  - Database Users
  - Network Peering
  - Private Endpoints
  - ...

示例2：创建集群（dry-run预检）

node （请参考skill目录中的脚本文件） \
  --category "Clusters" \
  --endpoint "Create Cluster" \
  --dry-run \
  --data '{
    "name": "prod-cluster",
    "clusterType": "REPLICASET",
    "providerSettings": {
      "providerName": "AWS",
      "regionName": "US_EAST_1",
      "instanceSizeName": "M10"
    },
    "replicationSpecs": [{
      "numShards": 1,
      "regionsConfig": {"US_EAST_1": {"electableNodes": 3, "priority": 7, "readOnlyNodes": 0}}
    }]
  }'

输出：

[dry-run] Request would be:
  POST /api/atlas/v2.0/groups/{groupId}/clusters
  Body: {"name": "prod-cluster", "clusterType": "REPLICASET", ...}
No changes applied. Remove --dry-run to execute.

示例3：创建数据库用户

node （请参考skill目录中的脚本文件） \
  --category "Database Users" \
  --endpoint "Create Database User" \
  --yes \
  --data '{
    "username": "app-user",
    "password": "SecurePass123!",
    "roles": [{"roleName": "readWrite", "databaseName": "myApp"}]
  }'

输出：

{
  "id": "60d5ec9b1234567890abcdef",
  "username": "app-user",
  "roles": [{"roleName": "readWrite", "databaseName": "myApp"}],
  "links": [{"href": "https://cloud.mongodb.com/api/atlas/v2.0/groups/.../databaseUsers/app-user"}]
}

示例4：搜索备份相关API

node （请参考skill目录中的脚本文件） catalog --search "backup"

输出：

Matching categories:
  - Backup (12 endpoints)
    - Create Backup Schedule
    - Get Backup Schedule
    - Update Backup Schedule
    - Delete Backup Schedule
    - Take Snapshot On-Demand
    - ...

常见问题集

Q1: 支持哪些API分类？

A: 覆盖50+分类，包括 Alerts、Atlas Search、Auditing、Backup、Clusters、Database Users、Network Peering、Private Endpoints、Monitoring、Logs 等。用 atlas-api.mjs catalog 查看完整列表.

Q2: --dry-run和--yes有什么区别？

A: --dry-run 只预检请求不实际执行，显示将要发送的HTTP方法和请求体。--yes 跳过交互确认直接执行。建议先用 --dry-run 预检再实际执行.

Q3: 如何配置API凭证？

A: 设置环境变量 ATLAS_CLIENT_ID 和 ATLAS_CLIENT_SECRET。这是公密钥认证方式，在云管理平台的API Keys页面创建.

Q4: 支持直接查询数据库吗？

A: 不支持。本工具仅管理云平台配置（集群、用户、网络、备份等），不执行数据库查询操作。查询请使用 mongosh 或应用程序驱动.

Q5: 如何查找特定功能的API？

A: 使用 atlas-api.mjs catalog --search "keyword" 按关键词搜索。例如搜索 "backup" 会列出所有备份相关的分类和端点.

Q6: API调用有速率限制吗？

A: 有。返回429状态码时表示触发速率限制，需等待60秒后重试。建议批量操作时控制调用频率.

Q7: --data参数的JSON格式有什么要求？

A: 必须是有效的JSON字符串。建议先用 jq 验证格式。命令行中JSON建议用单引号包裹，内部字符串用双引号.

功能边界

• 仅管理云平台配置，不执行数据库查询
• 需要预先配置 ATLAS_CLIENT_ID 和 ATLAS_CLIENT_SECRET
• API调用有速率限制，429时需等待重试
• --dry-run 不会实际执行，需去掉后加 --yes 才执行
• 覆盖50+分类的API端点，但部分高级功能可能需要直接调用原始API
• 环境变量在当前会话生效，新会话需重新设置

诊断与修复

安全保障

技术创新

效率指标

特色分析

异常处理指引

针对文档数据库管理使用中可能遇到的常见问题,提供以下排查方案:

文档数据库管理通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块