alibabacloud-data-agent-skill：本项目是一个 AI Agent Skill，让 AI 助手（如 OpenClaw、Claude、Qoder 等）能够调用阿里云瑶池 Data Agent，帮助企业用户通过自然语言完成数据分析任务。

更新日志

• v1.8.5 —— 数据库列表迁移到 ListTagMetaAsset（dms-enterprise 2018-11-01）；workspace 自动解析（CLI --workspace-id > 环境变量 DATA_AGENT_WORKSPACE_ID > InitDataAgentPersonalWorkspace）；db 子命令将 --dms-instance-id / --instance-name 放宽为可选。
• v1.8.4：补充项目 Python virtualenv（venv/）设置与激活说明；新增 ASK_DATA / ANALYSIS（异步 + attach）端到端回归说明
• v1.8.3：db 和 file 子命令现在接受 --session-mode CLAW
• v1.8.2：SendChatMessage 现在支持每条消息的 Mode=CLAW（通过 SessionConfig.Mode 注入）；通过 GetActiveRouteUnit 动态解析 DMSUnit
• v1.8.1：强调基于 attach 的会话复用是核心交互机制；新增黄金工作流、能力矩阵和使用规则
• v1.8.0：新增 workspace（协作空间）支持，新增自定义 agent 支持
• v1.7.2：使用阿里云默认凭证链替代显式 AK/SK，新增 User-Agent header，修复 RAM 策略通配符问题
• v1.7.1：修复 CLI ls 命令 API 响应解析（支持大小写不敏感字段名），优化 SKILL 文档结构，拆分 ANALYSIS 模式规范文档
• v1.7.0：支持 API_KEY 认证，原生异步执行模式，会话隔离，增强 attach 模式，优化日志输出

安装

Python 环境（venv）—— 必读

🚨 硬性要求：Python ≥ 3.10
macOS 系统 /usr/bin/python3 通常为 3.8 或 3.9，无法运行本项目（它依赖 match/case、TypeAlias、| union 语法等 3.10+ 特性）。
先验证版本：python3 --version。如果低于 3.10，通过 Homebrew 或 pyenv 安装：
```bash
# Homebrew
brew install python@3.12
# 或 pyenv
pyenv install 3.12.4 && pyenv local 3.12.4
```

⚠️ 必须使用 venv 虚拟环境。绝不要全局安装依赖。 对系统 Python 运行 pip install 会污染环境，并可能因权限问题失败。

使用现有 venv（推荐）

项目自带预构建的 venv/ 目录（所有依赖已预装）。尽可能使用它：

cd alibabacloud-data-agent-skill

选项 A（推荐）：激活 venv

source venv/bin/activate

python3 scripts/data_agent_cli.py ls

选项 B：直接调用 venv 解释器（无需激活）

venv/bin/python3 scripts/data_agent_cli.py ls

### 重建 venv

如果 `venv/` 缺失或依赖损坏，用 **3.10+** Python 重建：

python3.12 -m venv venv # 显式使用 3.10+ 解释器

source venv/bin/activate

pip install -r scripts/requirements.txt

> **提示**：本文档所有示例都写作 `python3 scripts/data_agent_cli.py ...`。venv 激活时，`python3` 自动解析为 venv 解释器；否则前缀 `venv/bin/python3`。

配置凭证

本 Skill 使用阿里云默认凭证链（推荐）或 API_KEY 认证。

选项 1：默认凭证链（推荐）

本 Skill 使用阿里云 SDK 的默认凭证链自动获取凭证，支持环境变量、配置文件、实例角色等。

参见 阿里云凭证链文档

选项 2：API_KEY 认证（仅文件分析）

export DATA_AGENT_API_KEY=your-api-key
export DATA_AGENT_REGION=cn-hangzhou

获取 API_KEY：Data Agent 控制台

权限要求

RAM 用户需要 AliyunDMSFullAccess 或 AliyunDMSDataAgentFullAccess 权限。

详细权限信息见 RAM-POLICIES.md。

调试模式

DATA_AGENT_DEBUG_API=1 python3 scripts/data_agent_cli.py file example.csv -q "analyze"

💡 快速上手提示

• 使用内置演示数据库 internal_data_employees（DataAgent 自带测试库，包含员工、部门和薪资数据）进行首次体验
• 或使用本地文件 assets/example_game_data.csv 进行文件分析体验

Data Agent CLI —— 统一命令行数据分析工具

概述

scripts/data_agent_cli.py 帮助用户完成从 发现数据 → 发起分析 → 跟踪进度 → 获取结果 的完整工作流。

核心概念

⚠️ 关键前置条件：Data Agent 只能分析已导入 Data Agent 数据中心的数据库。
- 数据中心：Data Agent 的数据中心，只有这里的数据库才能被分析
- DMS：阿里云数据管理服务，存储所有数据库的元数据
- 关系：在 DMS 中注册的数据库 ≠ 在数据中心中的数据库
使用流程：
1. 先用 ls 检查目标数据库是否存在于数据中心
2. 如果未找到，用 dms 子命令搜索数据库信息，再用 import 子命令导入
3. 导入成功后，即可用 db 子命令进行分析

分析模式

• ASK_DATA（默认）：同步执行，亚秒级响应，适合快速问答
• ANALYSIS：深度分析，耗时 5-40 分钟，需要生成子 agent 进行异步执行或使用 --async-run 参数
• INSIGHT：洞察导向探索，遵循与 ANALYSIS 相同的计划确认流程
• CLAW：Agentic CLAW 模式。两个入口：
• CLI：db --session-mode CLAW ... / file --session-mode CLAW ...（会话级）
• SDK：向 client.send_message(...) / AsyncDataAgentClient.send_message(...) 传 mode="CLAW"，通过 SessionConfig.Mode 覆盖单条消息的模式

端到端回归参考（v1.8.4 已验证）

ASK_DATA 和 ANALYSIS 模式都针对 chinook 数据库用异步 + attach 流程做过回归测试：

sessions/<SESSION_ID>/progress.log 中要查看的关键检查点：

• > User Query: ... —— 请求已接收
• ### Execution Plan (ID: ...) —— ANALYSIS 计划已生成，用 attach -q "confirm" 继续
• > ⚠️ Plan confirmed, continuing analysis... —— 计划已批准，开始执行
• ## Step N/M: ... —— 每步进度及产物链接
• ### Report Render + ⚠️ Please review the report rendering request. —— 可选 HTML 报告渲染确认

详情见 ANALYSIS_MODE.md

Workspace（协作空间）

Workspace 是协作空间，支持基于团队的数据分析，共享会话、数据源和访问控制。

• 列出 workspace：使用 workspace 子命令发现可用 workspace（个人或共享）
• 将会话绑定到 workspace：使用 db 或 file 时传 --workspace-id <ID>，在特定 workspace 上下文中创建会话
• Workspace 类型：MY（默认，个人空间）、ALL（所有可访问空间，包括共享空间）

注意：当会话在 workspace 内创建时，所有后续 API 调用（describe、send message 等）自动携带 workspace 上下文。

Workspace 解析

Workspace ID 按以下顺序自动解析：

1. CLI flag --workspace-id <id>
2. 环境变量 DATA_AGENT_WORKSPACE_ID
3. 通过 InitDataAgentPersonalWorkspace 自动创建个人 workspace

AK/SK 和 API_KEY 认证模式都支持此解析链。

自定义 Agent

自定义 Agent 是用户定义的 AI agent，具有专门指令、知识库和数据范围配置。

• 列出自定义 agent：使用 agent 子命令发现可用自定义 agent（默认 RELEASED 状态）
• 查看 agent 详情：使用 agent describe --custom-agent-id <ID> 查看完整 agent 配置
• 将会话绑定到自定义 agent：使用 db 或 file 时传 --custom-agent-id <ID>，创建由特定自定义 agent 驱动的会话

注意：自定义 Agent 会话自动使用 prod stage。自定义 agent 的指令、知识和数据范围将应用于分析会话。

通过 attach 复用会话（⭐ 核心机制）

最佳实践：attach 是推荐方式，用于与进行中或先前创建的会话交互。在同一数据范围的任何后续交互中，始终优先使用 attach，而非创建新会话。

为什么使用 attach

调用 db / file 启动会话后，该会话的所有后续交互都必须通过 attach --session-id <ID>。单个会话 = 服务端单个对话上下文，attach 是安全重新进入它的唯一方式。

黄金工作流（异步 + attach）

长时间分析的标准模式是 异步 db 启动 → 其余一切用 attach：

1) 启动异步分析，立即返回 SESSION_ID

python3 scripts/data_agent_cli.py db \

--dms-db-id <dbId> \

--db-name <schemaName> \

--tables "employees,departments" \

--workspace-id <workspace_id> \

--session-mode ANALYSIS \

-q "Analyze salary distribution"

-> ✅ Async task started. Session ID: abc123xyz

2) 实时查看进度（Ctrl-C 安全，服务端继续运行）

python3 scripts/data_agent_cli.py attach --session-id abc123xyz

3) 当 agent 进入 WAIT_INPUT 时确认或修改计划

python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "confirm"

4) 提问后续问题（复用上下文，无需重新导入、无需重新剖析）

python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "Break down by job level"

5) 如果流在第 219 个事件处被切断，精确恢复

python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219

6) 获取生成的报告 / 图表

python3 scripts/data_agent_cli.py reports --session-id abc123xyz

### 通过 `attach` 复用会话的好处

- **上下文保留** —— 之前的 SQL、表剖析和用户意图都保留，回答保持一致。
- **成本降低** —— 跳过每次提问重新发现 schema / 重新剖析表。
- **计划治理** —— ANALYSIS / INSIGHT 计划需要显式确认；只有 `attach -q "confirm"` 能解除阻塞。
- **韧性** —— `--checkpoint` / `--from-start` 让长时间任务对断网和客户端重启更稳健。
- **团队协作** —— 分享 Session ID，队友可 `attach` 同一会话查看进度和结果。

### 经验法则

1. 用 `db` / `file` 创建会话**一次**；其余一切用 `attach` 驱动。
2. 记录启动后打印的 `Session ID` —— 它是会话的唯一句柄。
3. 对于 ANALYSIS / INSIGHT 模式，始终用 `attach`（而非新 `db`）确认计划；创建新会话会丢失计划。
4. 会话产物（进度日志、检查点、结果、图片）持久化在 `sessions/<SESSION_ID>/` 下。

> 完整 `attach` 参数列表见 [COMMANDS.md](references/COMMANDS.md)，端到端场景见 [WORKFLOWS.md](references/WORKFLOWS.md)。

---

快速开始

1. 列出可用数据库

python3 scripts/data_agent_cli.py ls

示例输出：

chinook [mysql] dbId=abc123 instanceResourceId=rm-xxx catalogName=chinook

employees [mysql] dbId=def456 instanceResourceId=rm-yyy catalogName=employees

2. 创建会话进行初步分析（记录返回的 Session ID！）

python3 scripts/data_agent_cli.py db \

--dms-db-id <dbId> \

--db-name <schemaName> \

--tables <table1,table2> \

--workspace-id <workspace_id> \

-q "Which department has the highest average salary"

-> ✅ Async task started. Session ID: abc123xyz

3. ⭐ 复用会话 —— 后续提问、确认计划、监控进度

python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "Break down by month"

python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "confirm" # 批准 ANALYSIS 计划

python3 scripts/data_agent_cli.py attach --session-id abc123xyz # 跟踪实时进度

python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219 # 断线后恢复

4. 列出 workspace

python3 scripts/data_agent_cli.py workspace

5. 在特定 workspace 中查询

python3 scripts/data_agent_cli.py db \

--workspace-id <WORKSPACE_ID> \

--dms-db-id <dbId> \

--db-name <schemaName> \

--tables <table1,table2> -q "Which department has the highest average salary"

6. 列出可用自定义 agent

python3 scripts/data_agent_cli.py agent

7. 使用自定义 agent 分析

python3 scripts/data_agent_cli.py db --custom-agent-id <AGENT_ID> --dms-instance-id ... -q "your question"

> **记住**：`db` / `file` 只创建会话**一次**；所有后续操作都通过 `attach --session-id <ID>`。

> 📖 完整工作流、命令参考和最佳实践见 [WORKFLOWS.md](references/WORKFLOWS.md) 和 [COMMANDS.md](references/COMMANDS.md)

---

项目结构

                          # Skill 根目录
├── SKILL.md              # 本文档
├── scripts/              # 源代码
│   ├── data_agent/       # SDK 模块
│   ├── cli/              # CLI 模块
│   ├── data_agent_cli.py # CLI 入口
│   └── requirements.txt  # 依赖
├── sessions/             # 会话数据
└── references/           # 参考文档

文档 6 / 6：alibabacloud-mongodb-instances-manage