开源AI工作流

环境要求

• Python 3.10+
• 支持的操作系统：Windows、macOS、Linux

输出：单个 .html 文件，双击浏览器即可打开，零外部依赖

```

快速开始

安装步骤

1. 下载并解压 Skill 包

macOS / Linux:

   unzip echart-skill_*.zip -d ~/skills/
   cd ~/skills/echart-skill
   

Windows (PowerShell):

   Expand-Archive echart-skill_*.zip -DestinationPath $env:USERPROFILE\skills\
   cd $env:USERPROFILE\skills\echart-skill
   

1. 安装 Python 依赖

💡 网络不佳？ 如果发布包已包含 wheels/ 目录，直接使用下方的离线安装命令，无需联网下载。

在线安装（默认）：

   # 完整安装（核心 + 可选依赖，约 100 MB）
   pip install -r requirements.txt

   # 或仅核心依赖（约 40 MB，覆盖 90% 场景）
   pip install -r requirements-core.txt
   

离线安装（无需网络）：

   # macOS / Linux
   bash scripts/install.sh --offline

   # Windows
   scripts\install.bat --offline

   # 也可以只装核心依赖（更小更快）
   bash scripts/install.sh --offline --core-only
   

依赖说明：

| 文件 | 内容 | 大小 | 何时需要 | |------|------|------|----------| | requirements-core.txt | DuckDB, pandas, openpyxl 等 | ~40 MB | 总是需要 | | requirements-optional.txt | MySQL/PostgreSQL/MongoDB 驱动、轮询、测试 | ~60 MB | 连接外部数据库时 |

1. 导入到你的 Agent 平台

根据你使用的 Agent 平台，选择对应的安装方式：

Claude Code / OpenClaw

macOS / Linux:

   # 创建符号链接（推荐）
   ln -s ~/skills/echart-skill ~/.claude/skills/echart-skill

   # 或直接复制
   cp -r ~/skills/echart-skill ~/.claude/skills/
   

Windows (PowerShell):

   # 复制到 Claude Code skills 目录
   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills"
   Copy-Item -Recurse "$env:USERPROFILE\skills\echart-skill" "$env:USERPROFILE\.claude\skills\"
   

在项目根目录创建 CLAUDE.md：

   # 项目说明

   @~/.claude/skills/echart-skill/SKILL.md
   

Trae / WorkBuddy

   cp -r ~/skills/echart-skill ~/.trae/skills/
   # 或
   cp -r ~/skills/echart-skill ~/.workbuddy/skills/
   

Windows:

   Copy-Item -Recurse "$env:USERPROFILE\skills\echart-skill" "$env:USERPROFILE\.trae\skills\"
   Copy-Item -Recurse "$env:USERPROFILE\skills\echart-skill" "$env:USERPROFILE\.workbuddy\skills\"
   

1. 配置百度地图 AK（可选）

如需生成精细维度的地图（区县、街道），需配置百度地图 AK：

macOS / Linux:

   echo 'export BAIDU_AK=你的百度地图AK' >> ~/.zshrc
   source ~/.zshrc
   

Windows:

   setx BAIDU_AK "你的百度地图AK"
   

免费申请地址：百度地图开放平台

---

安装与配置

通用安装步骤

1. 下载最新版本的 echart-skill_*.zip 压缩包并解压。
2. 根据你所使用的 Agent 平台，选择对应的安装方式。
3. 安装 Python 依赖：

   # macOS / Linux
   bash scripts/install.sh              # 在线（需网络）
   bash scripts/install.sh --offline    # 离线（需 wheels/ 目录）

   # Windows
   scripts\install.bat                  # 在线
   scripts\install.bat --offline        # 离线
   

各平台安装方法

Claude Code

macOS / Linux: ```bash

📂 示例输出

examples/ 目录包含基于「订单详情表」的 9 个完整案例：

所有 HTML 文件均为自包含单文件，双击即可在浏览器打开。数据源：examples/订单详情表.csv（86 行 × 17 列）。

---

核心功能与使用案例

方式1：使用显性指令

/import sales_2024.xlsx

省份级别 - 使用 china.js

/chart map 中国各省销售分布

城市级别 - 使用省份 JS（如 guangdong.js）

/chart map 广东省各城市人口分布

区县街道 - 使用百度地图 API

/chart bmap 广州市天河区门店分布

**地图使用规则**：

| 层级 | 数据示例 | 使用方式 | 地图文件 |
|------|---------|---------|---------|
| 省份 | 北京、上海、广东 | `"map": "china"` | `china.js` |
| 城市 | 广州市、深圳市、东莞市 | `"map": "guangdong"` | `guangdong.js` |
| 区县 | 天河区、南山区 | `"bmap": {...}` | 百度地图 API |

#### 3D 图表

启动轮询

/poll start polling_config.txt

地图使用三层级架构

案例一：数据导入与自动清洗

场景：上传销售数据 Excel，自动识别并导入

操作：

```bash

案例二：SQL 查询与数据分析

场景：分析各地区销售情况

操作：

```bash

案例三：单图表生成

场景：生成各类统计图表

基础图表

```bash

案例四：专业 Dashboard 生成（自然语言）

场景：用自然语言快速生成多图表仪表盘

方法一：自然语言描述（推荐）

最简单的方式，直接描述想要的图表：

/dashboard 创建销售分析仪表盘，包含：
- 各地区销售柱状图
- 产品类别饼图
- 月度趋势折线图
- 全国分布地图

系统自动完成： 1. 解析图表类型和需求 2. 自动生成 SQL 查询 3. 智能布局排版 4. 生成专业仪表盘

方法二：简化 API（Python）

```python from scripts.simple_dashboard import SimpleDashboard

案例五：数据导出与报告生成

场景：导出查询结果或整表数据

```bash

案例六：外部数据库连接

场景：连接 MySQL 生产数据库查询数据

1. 创建连接配置（db_connections.txt）：

[connections.mysql_prod]
type=mysql
host=localhost
port=3306
database=production
username=reader
password=${MYSQL_PASSWORD}

2. 查询外部数据库：

```bash

案例七：数据轮询刷新

场景：定时从 API 自动刷新数据

1. 创建轮询配置（polling_config.txt）：

[jobs.sales_api]
source_type=http
source_name=sales_api
interval_seconds=300
table_name=live_sales
http_config.url=https://api.example.com/sales
http_config.format=json
http_config.auth.type=bearer
http_config.auth.token=${API_TOKEN}

2. 管理轮询任务：

```bash

地图配置（可选）

如果需要生成精细维度的地图（区县、街道），请设置环境变量 BAIDU_AK：

```bash

应用配置（echart_config.txt）

首次运行时系统会自动创建 echart_config.txt（默认配置如下），可按需修改：

server.enabled=false
server.port_range=8100,8200
output.dir=outputs/html
baidu_ak=

💡 提示： - 服务关闭时，生成图表后直接显示文件绝对路径（file:///...）。 - 所有图表 HTML 为自包含单文件，可在任意浏览器中离线打开。 - baidu_ak 优先级：环境变量 BAIDU_AK > echart_config.txt。

---

方法1：创建符号链接（推荐，方便更新）

ln -s /path/to/echart-skill ~/.claude/skills/echart-skill

方法2：直接复制

cp -r /path/to/echart-skill ~/.claude/skills/

**Windows (PowerShell):**

在项目根目录创建 `CLAUDE.md`：

ECharts 图表生成工作流 ⛔ 硬性约束

在线安装 vs 离线安装

💡 离线包说明：如果发布包 (echart-skill_*.zip) 内包含 wheels/ 目录（约 323 MB）， 用户端运行 install.sh / install.bat 时会自动检测并使用本地 wheels，完全跳过 PyPI 下载。 维护者生成离线包：bash scripts/download_wheels.sh && bash package.sh --offline。

常见问题 (FAQ)

Q: 为什么导入大 Excel 时有点慢？ A: 本技能为了应对"脏数据"，会在底层调用 openpyxl 来遍历并解开所有的合并单元格（Merged Cells）。这种物理层面的解析比直接读取纯数据稍慢，但能保证数据的完整性和准确性。

Q: 我发现 Agent 修改错数据了，怎么恢复？ A: 本技能内置了"后悔药"机制。你可以直接对 Agent 说："刚才那一步算错了，撤销"，Agent 会由于没有覆盖原表，直接回退到上一个表版本。

Q: 支持连接外部的 MySQL 或 PostgreSQL 吗？ A: 本技能目前默认使用本地 DuckDB 以追求开箱即用和零配置。DuckDB 采用列式存储，对分析型查询性能卓越。如果需要连接外部数据库，你可以让 Agent 修改生成的连接字符串，架构上是完全支持的。

Q: 如何从 API 接口导入数据？ A: 使用 /import url 命令，指定 URL 和格式即可导入。支持 Basic Auth 和 Bearer Token 认证。导入后可使用 refresh 命令刷新数据。

Q: 如何创建多图表仪表盘？ A: 创建一个 .txt 配置文件（内容可使用 JSON 结构表达复杂图表位置和配置），然后使用 /dashboard 命令生成即可。详见案例四示例。

Q: 地图如何选择正确的层级？ A: 省份数据用 china.js，城市数据用对应的省份 JS（如 guangdong.js），区县街道数据使用百度地图 API。系统会自动处理地图文件加载。

Q: Dashboard 支持哪些交互功能？ A: 支持主题切换（深色/浅色）、自动刷新、导出 PDF、图表搜索、单独下载图表等。所有功能都在 Dashboard 工具栏中提供。

---