Echart Skill — Enterprise Agent BI

本地优先 · 安全合规 · 企业级数据分析 Agent

🇬🇧 English  |  🇨🇳 中文

---

Echart Skill 不是单纯的图表生成器，而是一套面向企业数据分析全流程的 本地 Agent BI 能力包——将专业数据分析师的工作流（导入→清洗→口径定义→质量评估→分析→可视化→报告→审计）压缩为一个可复用的 AI Agent Skill。

核心主张：让企业在不引入重型 BI 平台、不上传业务数据、不把敏感数据交给大模型的前提下，用 AI Agent 完成专业、可审计、可交付的数据分析。

---

为什么选择 Echart Skill？

🔒 数据安全第一

🏢 企业级工作流集成

Echart Skill 深度融入企业数据管理体系，不只是查询工具：

• 自定义统计口径：通过 /scope 定义全局/项目级业务指标（如 GMV、客单价、转化率），保证不同报告和 Dashboard 使用同一口径。项目级口径仅在项目目录及子目录生效，互不干扰。
• 自定义表结构数据描述：通过 /schema 管理表结构定义（列名、类型、含义、主外键），Agent 生成 SQL 时自动引用精确的字段描述，避免猜测字段含义导致的查询错误。
• 三级配置体系：全局 → 项目级 → 运行时配置，数据库连接、表结构定义、统计口径均可按级别管理。
• 外部数据库直连：支持 MySQL / PostgreSQL / MongoDB 直连查询，无需预先导入 DuckDB；连接密码使用 ${ENV_VAR} 环境变量占位符，SQL 执行统一走 scripts/sql_runner.py / scripts/db_cli.py，杜绝硬编码和临时 Python 片段。
• 企业级输出门禁：任何查询、导出、报告、图表和 Dashboard 都必须具备统计口径、数据血缘/来源、生成时间、证据引用和专业版式；查询/导出自动生成 .meta.json 旁路元数据，HTML 产物通过静态质量门拦截坏布局。
• 图表数据可核验：每个图表区域必须提供“查看数据”按钮，默认隐藏对应数据表，点击后可查看该图实际使用的汇总数据或明细样本。
• 数据轮询刷新：支持 HTTP API / 外部数据库定时轮询，自动刷新本地分析表。
• 非破坏式操作：所有数据修改创建新表或视图，支持任意步骤回退（Undo）。

📊 专业分析引擎

🎨 企业级数据可视化

• 27 类图表：柱状/折线/饼图/散点/雷达/漏斗/仪表盘/热力图/树图/桑基图/关系图/K线/3D 等
• 354 个 ECharts 官方配方：Agent 无需手写 option 代码，直接替换数据数组即可生成
• 多层地图：省份（china.js）→ 城市（省份 JS）→ 区县街道（百度地图 API）
• 交互式 Dashboard：KPI 卡片、趋势图、异常提醒、主题切换、响应式布局、PDF/PNG 导出
• Dashboard 专家规划：生成前读取 workflow_specs/dashboard_expert_library/INDEX.md，新增专家按 workflow_specs/dashboard_expert_library/DASHBOARD_EXPERT_TEMPLATE.md 扩展
• Dashboard 深度门槛：业务 Dashboard 在数据支持时至少包含 6 个分析模块，标题必须可追溯到用户请求、文件、表名或真实字段
• 企业级视觉：统一 HTML 骨架、语义色、打印友好、暗色/亮色双主题

---

快速开始

环境要求

• Python 3.10+
• Windows / macOS / Linux

安装

# 1. 解压 Skill 包
unzip echart-skill_*.zip -d ~/skills/
cd ~/skills/echart-skill

# 2. 安装依赖
pip install -r requirements.txt        # 完整安装（~100 MB）
# 或
pip install -r requirements-core.txt   # 核心依赖（~40 MB，覆盖 90% 场景）

# 3. 注册到 Agent 平台
ln -s ~/skills/echart-skill ~/.claude/skills/echart-skill   # Claude Code

# 4. 开始使用
# 在项目目录创建 CLAUDE.md，添加 @~/.claude/skills/echart-skill/SKILL.md

30 秒体验

/import sales_2024.xlsx                        # 导入数据
/query SELECT region, SUM(amount) FROM sales_2024 GROUP BY region  # 查询
python scripts/sql_runner.py --db workspace.duckdb "SELECT COUNT(*) FROM sales_2024"
/chart bar 各区域销售额对比                      # 生成图表
/dashboard 创建销售分析仪表盘                    # 一键仪表盘
/report sales --format html                     # 生成企业报告
/quality sales_2024                             # 数据质量评分

---

核心能力图谱

                        ┌──────────────────────────────┐
                        │      企业决策与交付层          │
                        │  Dashboard  │  Report  │ 导出  │
                        └────────────┬─────────────────┘
                                     │
              ┌──────────────────────┼──────────────────────┐
              │                      │                      │
    ┌─────────▼─────────┐  ┌────────▼────────┐  ┌─────────▼─────────┐
    │   分析与洞察层      │  │   预测与归因层   │  │   可视化引擎层      │
    │ Insight Engine    │  │ Forecast/Attrib │  │ 27类 · 354配方     │
    │ 7 种洞察模式       │  │ 4 种方法 · 钻取  │  │ 地图 · 3D · 关系   │
    └─────────┬─────────┘  └────────┬────────┘  └─────────┬─────────┘
              │                     │                      │
              └──────────────────────┼──────────────────────┘
                                     │
                        ┌────────────▼────────────┐
                        │       数据治理层          │
                        │  口径  │  质量  │  血缘   │
                        │  审计  │  隐私  │  脱敏   │
                        └────────────┬────────────┘
                                     │
                        ┌────────────▼────────────┐
                        │       数据基础层          │
                        │  Import  │  Clean  │ DB  │
                        │  DuckDB  │ 外部数据库      │
                        └─────────────────────────┘

---

数据质量：让分析建立在可信数据之上

Echart Skill 将数据质量作为分析流程的前置环节，而非事后补救。

/quality orders --format markdown

质量报告包含：

• 完整性：每列缺失率、缺失模式分析
• 唯一性：重复行检测、疑似主键推荐
• 有效性：常量列检测（无信息列）、类型一致性
• 合规性：疑似 ID 字段标记、PII 风险提示
• 综合评分：A/B/C/D 四级，附带具体改进建议

生成企业报告或 Dashboard 前建议先跑质量评分。等级 C/D 或有 critical 问题时，报告结论自动标注「初步判断」并说明数据限制。

配合 /clean 的 Agent 引导式清洗流程（类型转换、多列唯一键排重、规则引擎校验、跨表验证），形成 质量评估 → 定向清洗 → 再次验证 的闭环。

---

自定义口径：企业级指标治理

在企业数据分析中，同一个指标在不同部门可能有不同定义。"口径不一致"是数据混乱的首要来源。Echart Skill 提供两级口径管理：

# 全局口径：所有项目生效
/scope set --level global --name "GMV" --desc "SUM(pay_amount) WHERE status='paid'"

# 项目口径：仅在当前项目目录及子目录生效
/scope set --level project --name "GMV" --desc "SUM(order_amount) WHERE is_valid=1"

# 查看当前生效的口径
/metrics effective

核心原则：

• 项目级口径同名覆盖全局口径
• 执行目录位于项目目录树内时，自动切换为项目口径
• Agent 生成 SQL/报告/Dashboard 时自动引用当前生效口径
• 所有使用口径的产物通过 /lineage 可追踪

---

自定义表结构：让 Agent 真正理解你的数据

数据表列名往往是缩写或业务术语（如 pay_amt、ch_type、uid）。通过 /schema 为表结构提供精确描述，Agent 生成 SQL 将显著提升准确性：

# 为表添加列级描述
/schema add --name orders --columns "
  id:INT:订单ID:pk,
  pay_amt:DECIMAL:实付金额(元),
  ch_type:VARCHAR:渠道类型(online/offline/partner),
  uid:INT:用户ID:fk->users.id
"

# 项目级定义（表结构仅在该项目可见）
/schema add --name orders --level project --columns "..."

# 查询当前生效的表结构
/schema list

---

安全与合规：从设计上保护数据

┌─────────────────────────────────────────────────────────────┐
│                     安全架构                                 │
│                                                             │
│   用户指令 ──→ Agent 规划 ──→ 本地执行 ──→ 本地输出          │
│                  │               │              │            │
│                  │          ┌────▼────┐         │            │
│                  │          │ DuckDB  │         │            │
│                  │          │ (本地)  │         │            │
│                  │          └────┬────┘         │            │
│                  │               │              │            │
│              Schema/       PrivacyGuard    Audit Pipeline    │
│              聚合结果       PII 检测·脱敏    指令·查询·Hash    │
│                  │               │              │            │
│                  └───────────────┼──────────────┘            │
│                                  │                           │
│                          大模型上下文                         │
│                     (仅含 schema + 聚合)                      │
└─────────────────────────────────────────────────────────────┘

安全防护清单：

外部数据库查询同样经过 PrivacyGuard 检测与审计管线，使用 /audit-report 统一查看。企业环境下可以写 SQL 和 .sql 文件，但不要使用 python3 --sql "" 或 python scripts/sql_runner.py --profile --file queries/.sql 执行。

---

30+ 命令速览

数据基础

可视化

分析引擎

治理与安全

运维

---

图表类型全景

地图三层级架构：

---

项目结构

echart-skill/
├── references/
│   ├── examples/               # 354 个 .md 自包含图表配方
│   │   └── INDEX.md            # 配方映射决策表
│   └── knowledge/              # ECharts 知识库（概念/API/模式）
├── workflow_specs/
│   ├── dashboard_workflow.md   # Dashboard 工作流规范
│   ├── report_workflow.md      # Report 工作流规范
│   ├── data_cleaning_workflow.md
│   ├── dashboard_runtime_quality.md  # 运行时质量门（硬性约束）
│   ├── dashboard_expert_library/     # Dashboard 专家库（5 个场景）
│   ├── expert_library/               # Report 专家库（10 个领域）
│   ├── dashboard_modules/            # Dashboard 可复用模块
│   ├── html_templates/               # 企业级 HTML 骨架
│   └── visual_templates/             # 视觉方向（亮色/暗色）
├── assets/                    # JS/CSS 资源、地图文件
├── scripts/                   # 40+ Python 工具脚本
├── tests/                     # 测试文件
└── outputs/                   # 输出目录

Dashboard 生成必须执行 workflow_specs/dashboard_runtime_quality.md 中的硬性质量门，并通过 python scripts/validate_delivery.py 。组合门禁会核对查询证据 manifest、静态结构、治理信息、无障碍/性能要求，并在真实 Chromium 中拦截 console/page error、外链请求、缺失图表实例和零尺寸 canvas/SVG；静态层仍会拦截未定义的 chinaGeoJSON 与 html2canvas 不兼容的 color-mix()。

---

FAQ

Q: 数据安全如何保证？ A: 原始数据仅存在于本地 DuckDB，大模型只接收 schema 和聚合结果。PII 自动检测脱敏，支持按列标记敏感级别。详见安全架构。

Q: 和传统 BI 工具（Tableau、Power BI）的区别？ A: Echart Skill 是 Agent BI——通过自然语言与 AI 交互完成分析，无需手动拖拽配置。同时它无需部署服务端、可离线运行、数据不出本地。适合需要专业分析但不想引入重型 BI 平台的场景。

Q: 如何定义我们公司的业务指标口径？ A: 使用 /scope set --level global --name "指标名" --desc "计算规则" 定义全局口径；不同项目可用 /scope set --level project 覆盖。Agent 在生成报告和 Dashboard 时自动引用当前生效口径。

Q: 如何让 Agent 准确理解我们数据库表的字段含义？ A: 使用 /schema add 为表的每个列提供中文描述、数据类型、合法值范围和主外键关系。Agent 会在生成 SQL 时精确引用，显著提升查询准确率。

Q: 支持连接公司已有的数据库吗？ A: 支持。/dbconn 管理 PostgreSQL/MySQL/MongoDB 连接，密码通过 ${ENV_VAR} 环境变量传入。SQL 查询使用 scripts/sql_runner.py --profile ，导入本地分析库使用 scripts/db_cli.py import，避免临时 Python 造成连接泄露、审计缺失和 SQL 拼接错误。

Q: 生成的报告和图表能否直接交付给客户？ A: 可以。Dashboard 和 Report 使用企业级 HTML 骨架，支持深色/亮色主题、PDF 导出、打印优化，图表为 ECharts 交互式可视化，可直接作为交付物。

Q: 分析过程是否可审计？ A: 完全可审计。/audit-report --date YYYY-MM-DD 按天输出指令、查询表、列、行数、脱敏状态、分类级别和 query hash。/lineage 追踪产物完整数据血缘。

---

许可证

MIT License — 详见 LICENSE

---

Built with ❤️ for data professionals who value privacy, quality, and efficiency.