---
name: echart-skill
description: 使用本地 SQL/DuckDB 分析 Excel、CSV 或数据库数据，并生成可审计、可离线运行的 ECharts 图表、Dashboard 和分析报告。适用于数据导入、清洗、查询、同比环比、诊断分析、可视化和企业 BI 交付。
---

# EChart Data Analysis Skill

Use this skill to turn structured data into evidence-backed analysis and
standalone ECharts deliverables. The invariant is not “an HTML file exists”; it
is that the data, metric definition, analysis claim, visual expression, and live
browser result all reconcile.

## Required pipeline

Follow these stages for every analysis. Read only the references needed for the
requested deliverable.

For recurring work, first run `python scripts/project_task.py list` from the
user project. Read **Reusable analysis tasks** in `workflow_specs/report_workflow.md`
when asked to save/repeat a successful analysis or a relevant task exists.
Match task purpose, not just a default name. Reuse approved SQL and templates;
do not redesign the analysis or copy last run's numbers/conclusions. `resolve`
returns questions for missing parameters: ask before executing. Ambiguous
task/period/filter means pause, never guess. Changed SQL, templates, cleaning,
metrics or report profiles require renewed review.

1. **Resolve data and business scope**
   - Read `workflow_specs/project_data_context.md` and run
     `python scripts/project_data_context.py resolve --query "<request>"` before
     searching directories, assuming a local database, or asking for a connection
     that may already be configured.
   - Use a resolved source; refresh `needs_refresh`, ask when `ambiguous`, and
     register any newly used project file. The canonical index is the project's
     `.echart-skill/data_sources.json`, never a file inside this Skill.
   - Inspect schema with maintained CLIs; do not load large tables into context.
   - Run `python scripts/metrics_manager.py effective` before defining metrics,
     filters, governed entity sets, comparison scope, or business terminology.
   - Never invent fields or approximate a governed set with keyword matching.
2. **Assess data fitness**
   - Discover project cleaning via `python scripts/project_cleaning.py status`.
     Read `workflow_specs/data_cleaning_workflow.md` for registration/approval.
     Rules live in `<project>/config/data_cleaning/`, never in this Skill.
     `sql_runner.py` and `analysis_runner.py` automatically apply approved rules
     to registered local DuckDB tables before aggregation. Do not substitute a
     different runner or raw source to bypass a cleaning failure.
   - When asked to remember a cleaning rule, register it in the project manifest,
     preview its impact, and approve only the user-confirmed scope. Subsequent
     analysis reuses it without another long prompt. Unknown/new/changed rules
     require confirmation; no rules means unchanged data, not guessed cleaning.
   - Run from the user project (absolute Skill script paths), or set
     `ECHART_PROJECT_ROOT` explicitly. External sources must be imported/refreshed
     through the maintained import path and bound to a local table; never clean
     remote production tables in place. Verify snapshot freshness before analysis.
   - Check date coverage, incomplete periods, nulls, duplicates, grain,
     uniqueness, units, currency, timezone, status filters, and known exclusions.
   - Use `scripts/data_quality.py` or `scripts/data_contract.py` when relevant.
3. **Query through the audited execution path**
   - Generate reviewable SQL and execute it with `scripts/sql_runner.py`,
     `scripts/db_cli.py`, or `scripts/db_manager.py`.
   - Never write temporary database connection code, heredoc Python,
     `duckdb.connect`, `psycopg.connect`, `pymysql.connect`, `create_engine`,
     `.cursor()`, or `cur.execute()`.
   - Write query results with `--out` so query hash and lineage metadata exist.
4. **Plan the analytical expression**
   - For Dashboards, first read `workflow_specs/dashboard_workflow.md` and run
     `python scripts/project_dashboard.py resolve` from the user project. Load
     registered project experts, required methods, layout and chart preferences.
     Read all referenced expert files; missing/changed profiles never silently
     fall back. This registry is independent of report profiles.
   - For reports, first read `workflow_specs/report_workflow.md` and run
     `python scripts/project_report.py resolve` from the user project. Reuse its
     analysis obligations, section order, layout and chart preferences. Read
     each referenced project expert note completely. Explicit task overrides
     take precedence but must not silently change the saved default.
   - When asked to remember a report scheme, save it under the user's
     `config/reports/`, register it in `manifest.json`, and validate with
     `resolve`. Never save business methods or branding inside this Skill.
     Dashboard schemes and project experts similarly live under the user's
     `config/dashboards/` (expert Markdown may live elsewhere inside that project).
     Set the requested default once; later requests reuse it without re-asking.
   - Read [analysis expression quality](workflow_specs/analysis_expression_quality.md).
   - Write an analysis-plan JSON and run
     `python scripts/validate_analysis_plan.py <plan.json>`.
   - Use Message → Relation → View. Select views through
     `references/chart_capabilities.json` or
     `python scripts/chart_capabilities.py <view-request.json>`.
   - Distinguish the hidden audit/source table from a visible analytical
     companion table.
5. **Bind evidence instead of restating it**
   - Read `workflow_specs/artifact_evidence_contract.md`.
   - Create a draft artifact manifest that references actual query result files.
   - For compiled charts, pass `--evidence <draft.json>` to the builder; it binds
     and validates before publishing. Custom HTML uses
     `python scripts/artifact_manifest.py bind <output.html> <draft.json>`.
   - The binder computes query-result SHA-256, row count, date coverage, and
     binds query hashes, metric/scope fingerprints, comparisons, charts, and
     findings into the HTML.
6. **Compile charts and compose the layout**
   - Read `references/chart_guide.md`. For supported common charts, use
     `scripts/chart_builder.py` with explicit query-result field mappings.
     Use `--evidence` to require the full gate before replacing the output.
     Do not copy demo arrays or rewrite the maintained bootstrap.
   - For specialized views, retrieve one archived reference through
     `scripts/reference_assets.py get <name>` and verify its dependencies.
     Old demo replacement instructions are superseded by the chart guide.
   - Dashboard: read `workflow_specs/dashboard_workflow.md` and
     `workflow_specs/dashboard_runtime_quality.md`. Use
     `scripts/project_dashboard.py build <spec.json> --evidence <draft.json>
     --output <dashboard.html>` for supported views. It applies the project
     scheme, binds KPI values directly to query results, and runs full gates.
   - Report: use `scripts/project_report.py build <spec.json> --evidence
     <draft.json> --output <report.html>`. It applies the resolved profile and
     blocks missing methods/evidence, stale profiles and unexplained view
     overrides. Methods require actual audited queries or visible data gaps,
     not canned conclusions. No configured profile uses generic defaults.
   - Report/Dashboard specs require `statistical_scope`: source, date coverage,
     grain, metric formulas, grouping, filters/exclusions, cleaning, unit,
     currency, timezone and limitations. It is visible globally, per section
     and per chart; override where scope differs. Do not invent missing metadata
     or fill with boilerplate. Ask or disclose unknowns and avoid affected claims.
   - Use the project generators' responsive shells or a configured passive
     project HTML shell; validation is mandatory. The dashboard_light.html
     template remains a reference for separately verified custom dashboards.
7. **Run the complete delivery gate**
   - Run `python scripts/validate_delivery.py <output.html>`.
   - This combines static ECharts/runtime checks, governance checks, manifest
     reconciliation, and a real Playwright/Chromium render.
   - Any console error, page error, external request, missing ECharts instance,
     zero-size canvas/SVG, evidence mismatch, or invalid comparison blocks
     delivery.
   - Mark all custom chart roots `data-echart-chart`; retain compiler contracts.
     Every expected chart must initialize. Compiled series data and axes must
     match the specification, with desktop and mobile render checks.
   - Source-data controls must pass actual open/close clicks on desktop/mobile,
     not merely contain a handler name. Scope text must be visible. Label query
     tables as potentially aggregated/masked, not raw transaction records.
     Raw-detail drill-down needs separate audited, authorized, privacy-safe data.
     Legacy buttons must indicate expanded/collapsed state; place revealed data
     near its control or bring it into view. Off-screen expansion without feedback
     is not a usable interaction. Native details/summary is preferred.
   - `--allow-static-only` is a degraded exception only when browser execution
     is genuinely unavailable; disclose that reduced assurance.

## SQL execution contract

Preferred examples:

```bash
python scripts/schema_manager.py show <table>
python scripts/sql_runner.py --db workspace.duckdb --file queries/<task>.sql \
  --output json --out outputs/query_results/<task>.json
python scripts/sql_runner.py --profile <profile> --file queries/<task>.sql \
  --output json --out outputs/query_results/<task>.json
```

For one-off external connections, pass credentials only through approved
environment-backed CLI parameters such as `--password-env` or `--dsn-env`.
Project queries, connection profiles, outputs, logs, and generated packages are
local state and must never be added to the reusable skill release.

## Comparison and metric correctness

All YoY, QoQ, MoM, WoW, period, and cohort comparisons must declare:

- current and baseline start/end;
- complete or partial status;
- latest complete period;
- calendar type: calendar, fiscal, retail 4-4-5, or custom;
- alignment rule and comparability;
- visible current/baseline labels;
- evidence query IDs and metric IDs;
- identical current/baseline fingerprints for metric definition, entity scope,
  filters, unit, currency, and timezone.

YTD-versus-full-year and partial-versus-complete comparisons are blocking
failures. Fiscal and retail calendars align governed named periods rather than
being forced onto calendar-month boundaries.

An HTML comparison must contain both `analysis-comparison-contract` and
`analysis-artifact-manifest`. The declared windows must match each other and the
actual dates in the bound query result files.

Before computing any change, validate both windows with `validate_comparison`.
`analysis_runner.py period-compare` requires `--comparison-contract <json>` and
checks daily coverage per group in the same SQL; failure produces no result file.
The legacy category comparison command rejects recognized temporal labels.
Complete calendar MoM/QoQ requires whole adjacent months/quarters; WoW requires
adjacent seven-day windows. Partial windows require equal elapsed days and
aligned starts. Never fix a failed check by changing `partial` to `complete`.
Missing dates block comparison even when min/max dates look correct: bind daily
coverage evidence for every day in both windows (see artifact evidence contract).
Unknown/no-activity days are not interchangeable; never fabricate zero rows.

Numeric YoY/MoM/etc. table rows, including hidden chart source tables, must carry
`comparison_id`, `current_start/end`, `baseline_start/end` from query results;
generators preserve these as `data-*` attributes and the gate reconciles each
row with its registered contract. One valid page-level comparison does not cover
other rows. For incomplete or unavailable baselines output null/“—” with a reason,
not a growth number plus a disclaimer. Apply this to ratios as well as totals;
remove dependent conclusions/actions when a comparison is invalid. Do not imply
complete analytical correctness from browser or structural validation alone.

## Findings and analytical depth

Every major finding must state What, baseline, Why status, Why, So what, next
check, evidence references, and limitations.

- `tested`: allowed only when the artifact manifest references an executed next
  check query.
- `hypothesis`: a plausible explanation that still needs testing.
- `unknown`: insufficient evidence; state the missing data.

Correlation, ranking, trend, anomaly, and composition detectors produce
descriptive candidates, not causal conclusions. Drill down through contribution,
segment, volume × rate/price, anomaly/data-quality, and stability/sample-size
checks when the data supports them.

## Visual and table contract

- Prefer position and length encodings over angle, area, volume, and decorative
  effects.
- A pie chart is limited to 2–3 positive categories and approximate share.
- Use a visible companion table for exact lookup, high-density comparison,
  exceptions, risk/action lists, or four-plus measures.
- Every chart still needs a default-hidden `查看数据` source table, chart-level
  statistical scope, data source, and evidence/query reference.
- Include units, readable labels, semantic colors, responsive sizing, and a
  text/table fallback. Do not rely on color alone.
- Do not invent a product, brand, industry label, or title that is absent from
  the request, governed scope, schema, and evidence.
- Mixed bar/line charts with different units or magnitudes require separate
  y-axes and explicit `yAxisIndex: 0` / `yAxisIndex: 1` assignment.

## Standalone HTML and runtime contract

- Inline ECharts and required local assets; no CDN, runtime loader, `fetch()` to
  external URLs, iframe/object/embed, self-navigation, or `file://` nesting.
- Load libraries before chart bootstrap. Use literal `</script>` closing tags.
- Serialize data with `json.dumps(..., ensure_ascii=False, default=str)`; never
  hand-write large JavaScript data objects or call `JSON.parse({...})`.
- Use real responsive chart dimensions and resize handling.
- Dashboard runtime rules cover map registration including accidental
  `chinaGeoJSON` references, PDF export compatibility including `color-mix()`,
  card/grid density, data-table controls, and export/download behavior.

## Routing references

| Request | Read |
|---|---|
| Import or cleaning | `workflow_specs/data_cleaning_workflow.md` |
| Locate database/file data | `workflow_specs/project_data_context.md` |
| Chart selection | `workflow_specs/analysis_expression_quality.md`, `references/chart_capabilities.json` |
| Dashboard | `workflow_specs/dashboard_workflow.md`, `workflow_specs/dashboard_runtime_quality.md` |
| Report | `workflow_specs/report_workflow.md` |
| Save/repeat tasks, parameterized SQL | `workflow_specs/report_workflow.md` → Reusable analysis tasks |
| Domain analysis | `workflow_specs/expert_library/INDEX.md` |
| Domain dashboard | `workflow_specs/dashboard_expert_library/INDEX.md` |
| Individual commands or CLI detail | `commands/echart/*.md` |

When adding a reusable dashboard expert, start from
`workflow_specs/dashboard_expert_library/DASHBOARD_EXPERT_TEMPLATE.md`; never
place a project-specific dashboard or query in the skill.

## Release hygiene

Run:

```bash
bash package.sh
python scripts/validate_release_package.py dist/<package>.zip
# For upload limits: four-file package with the same common-chart engine/gates
python scripts/build_skill_package.py --mode portable --output dist/echart-portable.zip
```

The package uses an allowlist. Project SQL, database connection files, outputs,
logs, caches, tests, and local indexes are forbidden release content.
The portable package embeds its tools in runtime.zip, verified and expanded by
bootstrap.py in the user project's .echart-runtime cache. Python and browser
runtimes are still required; specialized historical demos/GL use the full package.