echart-skill git:20261014.675baa2A

Immutable. This exact content never changes and is served at /api/v1/blob/7fcc7673a4d89739.

---
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**
   - 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**
   - 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: read `workflow_specs/report_workflow.md`.
   - Use `workflow_specs/html_templates/dashboard_light.html` or
     `workflow_specs/html_templates/report_light.html` as the relevant shell.
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.