alibabacloud-data-agent-skill

metadata: author: DataAgent Team version: "1.8.6"

更新日志

• v1.8.6：修复服务器省略 event: 前缀行时的 SSE 解析问题（将 JSON 负载中的 event_type 提取为回退值）；为所有 SSE 流式传输方法（GetChatContent）添加 DMSUnit；为 db、file、attach 子命令添加 --dms-unit CLI 标志；为 attach 子命令添加 --workspace-id CLI 标志；DMSUnit 解析会优先使用环境变量／配置／CLI 覆盖值，然后调用 GetActiveRouteUnit，最后回退到区域值。
• v1.8.5 — 数据库列表已迁移至 ListTagMetaAsset（dms-enterprise 2018-11-01）；工作区自动解析（CLI --workspace-id > 环境变量 DATA_AGENT_WORKSPACE_ID > InitDataAgentPersonalWorkspace）；db 子命令的 --instance-name 参数现为可选。
• v1.8.4：记录项目 Python 虚拟环境（venv/）的设置和激活方式；添加 ASK_DATA / ANALYSIS 端到端回归说明（异步 + attach）
• v1.8.3：db 和 file 子命令现可接受 --session-mode，并采用简化的模式层级
• v1.8.2：SendChatMessage 现支持按消息覆盖模式（通过 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 文档结构，分离 pro 模式规范文档
• 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（推荐）

请在技能目录（alibabacloud-data-agent-skill/）下操作。如果存在预构建的 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 身份验证。

环境变量

变量	说明	默认值
DATA_AGENT_API_KEY	API Key 身份验证（文件分析场景）	—
DATA_AGENT_REGION	区域 ID	cn-hangzhou
DATA_AGENT_DMS_UNIT	覆盖 DMSUnit（别名 DATA_AGENT_DMSUNIT）	自动解析
DATA_AGENT_WORKSPACE_ID	默认工作区 ID	自动选择个人工作区
DATA_AGENT_CUSTOM_AGENT_ID	默认自定义 Agent ID	—
DATA_AGENT_ENDPOINT	自定义端点	自动生成
DATA_AGENT_DMS_ENTERPRISE_ENDPOINT	用于发现 API 的 dms-enterprise 主机（不受 DATA_AGENT_ENDPOINT 覆盖）；仅通过 VPC 出网时需设置	dms-enterprise.{region}.aliyuncs.com
DATA_AGENT_TIMEOUT	请求超时时间（秒）	300
DATA_AGENT_MAX_RETRY	最大重试次数	3
DATA_AGENT_POLL_INTERVAL	轮询间隔（秒）	2
DATA_AGENT_MAX_POLL_COUNT	最大轮询次数	60
DATA_AGENT_DEBUG_API	打印 API 请求详情	false

所有变量均可在 .env 文件中设置，或导出为环境变量。CLI 标志（--dms-unit、--workspace-id、--custom-agent-id）会覆盖对应的环境变量。

选项 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：Alibaba Cloud Data Management Service，存储所有数据库的元数据
• 关系：在 DMS 中注册的数据库 ≠ Data Center 中的数据库

使用流程：

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

---

会话模式

• auto（默认）：由后端智能决策，根据查询复杂度自动选择最佳模式
• lite：快速查询模式，响应时间不到一秒，适用于快速问答和简单 SQL 查询
• pro：深度分析，耗时 5-40 分钟，需要启动子 Agent 异步执行或使用 --async-run 参数
• ultra：最全面的分析，提供多维度见解，遵循与 pro 相同的计划确认流程

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

轻量模式和专业模式均已针对 chinook 数据库进行回归测试，使用异步 + attach 流程：

模式	启动方式	观测到的流程	典型时长
lite	db --session-mode lite -q "..."	异步工作线程 → 实时 SSE → result.json={"status":"completed"}	约 15 秒
pro	db --session-mode pro -q "..."	异步工作线程 → 计划 → WAIT_INPUT → attach -q "confirm" → 逐步执行 → Excel/Chart 产物 → 文本报告 → 第 2 次 WAIT_INPUT（网页渲染）	2–10 分钟（文本）；若渲染网页则额外 +10 分钟

请在 sessions/<SESSION_ID>/progress.log 中留意以下关键检查点：

• > User Query: ... — 已收到请求
• ### Execution Plan (ID: ...) — 已生成专业/超高模式计划，使用 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、send message 等）都会自动携带工作区上下文。

工作区解析

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

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

AK/SK 和 API_KEY 两种身份验证模式均支持此解析顺序。

DMSUnit 解析

DMSUnit 按以下顺序自动解析：

1. 环境变量 DATA_AGENT_DMS_UNIT
2. 通过 GetActiveRouteUnit 动态查找路由
3. 从 DATA_AGENT_REGION 获取区域回退值

仅当租户必须使用特定 DMSUnit 时，才设置 DATA_AGENT_DMS_UNIT。若使用自动路由查找，请将其留空。

ListTagMetaAsset 数据发现仍按区域限定，并在 sys::DMS-DA::<region>::space:<workspace> 等标签中使用 DATA_AGENT_REGION。

---

自定义 Agent

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

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

注意：指定 --custom-agent-id 后，无需传入数据源参数（--dms-instance-id、--dms-db-id、--db-name、--tables），也不应传入这些参数。自定义 Agent 已有自己的数据范围配置。只需使用 --workspace-id 和会话选项（例如 --session-mode、--plan-mode）。

注意：自定义 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"	批准 pro / ultra 模式生成的执行计划
修改计划	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	attach --session-id <ID> --dms-unit cn-hangzhou --workspace-id <WS>	覆盖会话的 DMSUnit 和工作区

标准工作流（异步 + attach）

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

# 1) Kick off async analysis, returns SESSION_ID immediately
python3 scripts/data_agent_cli.py db \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables "employees,departments" \
    --workspace-id <workspace_id> \
    --session-mode pro \
    -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、表分析和用户意图，使回答保持一致。
• 降低成本 — 无需在每次提问时重新发现架构 / 重新分析表。
• 计划治理 — pro / ultra 计划需要明确确认；只有 attach -q "confirm" 才能批准执行。
• 增强韧性 — --checkpoint / --from-start 让长时间运行的任务能够抵御网络中断和客户端重启。
• 团队协作 — 分享 Session ID，团队成员可以 attach 到同一会话，查看进度和结果。

经验法则

1. 只使用 db / file 创建一次会话；其他所有操作都使用 attach。
2. 记录启动后打印的 Session ID — 它是访问该会话的唯一凭据。
3. 对于 pro / ultra 模式，始终使用 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-instance-id <DMS_INSTANCE_ID> \
    --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 pro/ultra 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 \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --workspace-id <WORKSPACE_ID> \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> -q "Which department has the highest average salary"

# 5b. Query with explicit DMSUnit (e.g. cn-shenzhen region, cn-hangzhou DMSUnit)
DATA_AGENT_REGION=cn-shenzhen python3 scripts/data_agent_cli.py db \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --workspace-id <WORKSPACE_ID> \
    --dms-unit cn-hangzhou \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> -q "your question"

# 6. List available custom agents
python3 scripts/data_agent_cli.py agent

# 7. Use a custom agent for analysis (no DB params needed)
python3 scripts/data_agent_cli.py db --custom-agent-id <AGENT_ID> --workspace-id <WS_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