alibabacloud-data-agent-skill

metadata: author: DataAgent Team version: "1.8.5"

更新日志

• v1.8.5 — 数据库列表迁移至 ListTagMetaAsset（dms-enterprise 2018-11-01）；工作区自动解析（CLI --workspace-id > 环境变量 DATA_AGENT_WORKSPACE_ID > InitDataAgentPersonalWorkspace）；db 子命令将 --dms-instance-id / --instance-name 调整为可选参数。
• v1.8.4：记录项目 Python 虚拟环境（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：添加工作区（协作空间）支持，添加自定义 Agent 支持
• v1.7.2：使用 Alibaba Cloud 默认凭证链替代显式 AK/SK，添加 User-Agent 标头，修复 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、| 联合类型语法及其他 3.10+ 特性）。

请先检查版本：python3 --version。如果低于 3.10，请通过 Homebrew 或 pyenv 安装：

# Homebrew
brew install [email protected]
# Or pyenv
pyenv install 3.12.4 && pyenv local 3.12.4

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

使用现有 venv（推荐）

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

cd alibabacloud-data-agent-skill

# Option A (recommended): activate the venv
source venv/bin/activate
python3 scripts/data_agent_cli.py ls

# Option B: invoke the venv interpreter directly (no activation needed)
venv/bin/python3 scripts/data_agent_cli.py ls

重建 venv

如果缺少 venv/ 或依赖已损坏，请使用 3.10+ 的 Python 重新创建：

python3.12 -m venv venv          # explicitly use a 3.10+ interpreter
source venv/bin/activate
pip install -r scripts/requirements.txt

提示：本文档中的所有示例均使用 python3 scripts/data_agent_cli.py ...。激活 venv 后，python3 会自动解析为 venv 解释器；否则请使用 venv/bin/python3 前缀。

配置凭证

此 Skill 使用 Alibaba Cloud 默认凭证链（推荐）或 API_KEY 身份验证。

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

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

请参阅 Alibaba Cloud 凭证链文档

选项 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 Center 的数据库。

• Data Center：Data Agent 的数据中心，只有这里的数据库才能进行分析
• DMS：阿里云数据管理服务，用于存储所有数据库的元数据
• 关系：在 DMS 中注册的数据库 ≠ Data Center 中的数据库

使用流程：

1. 首先使用 ls 检查目标数据库是否存在于 Data Center 中
2. 如果未找到，使用 dms 子命令搜索数据库信息，然后使用 import 子命令导入数据库
3. 导入成功后，即可使用 db 子命令进行分析

---

分析模式

• ASK_DATA（默认）：同步执行，响应时间不到 1 秒，适合快速问答
• ANALYSIS：深度分析，耗时 5-40 分钟，需要启动子 Agent 异步执行，或使用 --async-run 参数
• INSIGHT：以洞察为导向的探索，采用与 ANALYSIS 相同的计划确认流程
• CLAW：Agent 化的 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 流程：

模式	启动命令	观察到的流程	典型耗时
ASK_DATA	db --session-mode ASK_DATA -q "..."	异步工作进程 → 实时 SSE → result.json={"status":"completed"}	~15s
ANALYSIS	db --session-mode ANALYSIS -q "..."	异步工作进程 → 计划 → WAIT_INPUT → attach -q "confirm" → 逐步执行 → Excel/Chart 产物 → 文本报告 → 第二次 WAIT_INPUT（网页渲染）	2-10 分钟（文本）；若渲染网页则额外 +10 分钟

请在 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 子命令查看可用的工作区（个人或共享）
• 将会话绑定到工作区：使用 db 或 file 创建会话时，传入 --workspace-id <ID>，以在指定的工作区上下文中创建会话
• 工作区类型：MY（默认，个人空间）、ALL（所有可访问的空间，包括共享空间）

注意：在工作区中创建会话后，所有后续 API 调用（describe、发送消息等）都会自动携带工作区上下文。

工作区解析

系统按以下顺序自动解析工作区 ID：

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

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 阶段。自定义 Agent 的指令、知识和数据范围将应用于分析会话。

---

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

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

为什么使用 attach

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

功能	命令	场景
后续提问	attach --session-id <ID> -q "..."	在完整上下文中继续对话，跳过数据理解开销
确认计划	attach --session-id <ID> -q "confirm"	批准 ANALYSIS/INSIGHT 模式生成的执行计划
修改计划	attach --session-id <ID> -q "simplify to 3 steps"	执行前优化计划
监控进度	attach --session-id <ID>（不带 -q）	实时跟踪长时间运行会话的 SSE 进度
网络中断后恢复	attach --session-id <ID> --checkpoint <N>	中断后从第 N 个事件精准恢复
重放完整历史记录	attach --session-id <ID> --from-start	从事件 0 开始重新流式传输整个会话

标准工作流（异步 + attach）

长时间运行的分析的标准模式是：异步启动 db → 其他所有操作都使用 attach：

# 1) Kick off async analysis, returns SESSION_ID immediately
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) Watch progress live (Ctrl-C is safe, server keeps running)
python3 scripts/data_agent_cli.py attach --session-id abc123xyz

# 3) Confirm or modify the plan when agent enters WAIT_INPUT
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "confirm"

# 4) Ask follow-up questions (reuses context, no re-import, no re-profiling)
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "Break down by job level"

# 5) Recover precisely if the stream was cut at event #219
python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219

# 6) Fetch generated reports / charts
python3 scripts/data_agent_cli.py reports --session-id abc123xyz

通过 attach 复用会话的优势

• 保留上下文 — 保留先前的 SQL、表分析和用户意图，确保回答一致。
• 降低成本 — 无需在每个问题上重新发现架构或重新分析表。
• 计划管理 — 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>/ 下。

请参阅 COMMANDS.md，了解完整的 attach 参数列表；端到端场景请参阅 WORKFLOWS.md。

---

快速开始

# 1. List available databases
python3 scripts/data_agent_cli.py ls
# Example output:
#   chinook [mysql]  dbId=abc123  instanceResourceId=rm-xxx  catalogName=chinook
#   employees [mysql]  dbId=def456  instanceResourceId=rm-yyy  catalogName=employees

# 2. Create a session for initial analysis (record the returned 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. ⭐ Reuse the session — follow-up questions, confirm plans, monitor progress
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"     # approve ANALYSIS plan
python3 scripts/data_agent_cli.py attach --session-id abc123xyz                  # tail live progress
python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219 # resume after drop

# 4. List workspaces
python3 scripts/data_agent_cli.py workspace

# 5. Query in a specific 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. List available custom agents
python3 scripts/data_agent_cli.py agent

# 7. Use a custom agent for analysis
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 和 COMMANDS.md

---

项目结构

                          # Skill root directory
├── SKILL.md              # This document
├── scripts/              # Source code
│   ├── data_agent/       # SDK module
│   ├── cli/              # CLI module
│   ├── data_agent_cli.py # CLI entry point
│   └── requirements.txt  # Dependencies
├── sessions/             # Session data
└── references/           # Reference documents