echart-skill git:20261017.3ff82caA

Immutable. This exact content never changes and is served at /api/v1/blob/591d54ec940acabd.

---
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.

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 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.
   - 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`.
   - 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.
   - Use `workflow_specs/html_templates/dashboard_light.html` or
     the project-report generator's responsive shell. A configured passive
     project HTML shell can replace the report shell; validation is mandatory.
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.
   - `--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.

## 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` |
| 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.