ECharts ChartPage

echarts-chartpage ist ein TypeScript-Toolkit, das strukturierte JSON-Daten, Visualisierungsziele und Feldzuordnungen in sichere, ausführbare HTML-Diagrammseiten umwandelt, die auf Apache ECharts basieren.

Es wird bereitgestellt als:

• ein npm-Paket für die programmatische Nutzung

• eine CLI für lokale Automatisierung

• ein MCP-Server für Agenten-Workflows

Das Projekt ist auf deterministische Ausgabe, kontrollierte Optionsgenerierung, strenge Validierung und öffentliche Open-Source-Wartbarkeit ausgelegt.

Funktionen

• Generierung vollständiger HTML-Diagrammseiten in einer einzigen Datei inklusive Apache ECharts CDN

• Abhängigkeit vom offiziellen echarts npm-Paket im Quellcode für Typen und Integrationskorrektheit

• Akzeptiert strukturierte Daten sowie Eingaben für goal, theme und Feldzuordnungen

• Empfiehlt sichere Diagrammtypen aus einer kontrollierten Whitelist

• Erstellt kontrollierte ECharts-Optionen ohne willkürliche JS-Formatter-Injektion

• Validiert Schema, Feldzuordnungen, Diagrammkompatibilität und grundlegende HTML-Strukturen

• Patcht bestehende Diagrammspezifikationen und generiert die Ausgabe neu

• Wiederverwendung eines gemeinsamen Kerns über npm-API, CLI und MCP-Server

• Auslieferung mit Tests, CI, Beispielen, Dokumentation für Mitwirkende und release-fertiger Paketierung

Unterstützte Ziele

• trend

• compare

• composition

• distribution

• ranking

• correlation

Unterstützte Diagrammtypen

• line

• bar

• stacked_bar

• pie

• donut

• scatter

• area

• table

Installation

npm install echarts-chartpage

Für die lokale Entwicklung:

npm install

Schnellstart

CLI

npx echarts-chartpage generate \
  --input examples/inputs/line-chart.json \
  --output revenue-trend.html

npm API

import { generateChartPage } from "echarts-chartpage";

const result = generateChartPage({
  title: "Monthly Revenue Trend",
  goal: "trend",
  theme: "light",
  outputMode: "single_html",
  data: [
    { month: "2025-01", revenue: 120 },
    { month: "2025-02", revenue: 132 },
    { month: "2025-03", revenue: 148 }
  ],
  fields: {
    x: "month",
    y: "revenue"
  }
});

console.log(result.chartType);
console.log(result.html);

MCP-Server

Zuerst bauen, dann den stdio-Server starten:

npm run build
npm run mcp:start

Eingabemodell

type GenerateChartPageInput = {
  title: string;
  description?: string;
  goal: "trend" | "compare" | "composition" | "distribution" | "ranking" | "correlation";
  data: Array<Record<string, string | number | boolean | null>>;
  fields: {
    x: string;
    y: string | string[];
    series?: string;
    category?: string;
  };
  theme?: "light" | "dark";
  outputMode?: "single_html";
  chartType?: "line" | "bar" | "stacked_bar" | "pie" | "donut" | "scatter" | "area" | "table";
};

Ausgabe

generateChartPage() gibt Folgendes zurück:

• normalisierte Spezifikation

• aufgelöster Diagrammtyp

• Warnungen

• kontrollierte ECharts-Option oder null für Tabellen-Fallback

• vollständiges ausführbares HTML

CLI-Nutzung

Der Name der CLI-Binärdatei lautet echarts-chartpage.

generate

Generiert eine einzelne HTML-Seite aus einer JSON-Eingabe:

echarts-chartpage generate \
  --input examples/inputs/line-chart.json \
  --output examples/generated/line-chart.html

recommend

Empfiehlt einen Diagrammtyp:

echarts-chartpage recommend \
  --input examples/inputs/bar-chart.json

validate

Validiert die Eingabe und optional das generierte HTML:

echarts-chartpage validate \
  --input examples/inputs/pie-chart.json \
  --html examples/generated/pie-chart.html

patch

Patcht eine Basis-Diagrammspezifikation und generiert das HTML neu:

echarts-chartpage patch \
  --base examples/inputs/patch-base.json \
  --patch examples/inputs/patch-update.json \
  --output examples/generated/patch-example.html

MCP-Nutzung

Der Server stellt diese Werkzeuge bereit:

• recommend_chart_type

• generate_chart_page

• validate_chart_page

• patch_chart_page

Alle Werkzeugeingaben und -ausgaben sind strukturiertes JSON. Eine typische MCP-Client-Konfiguration verweist auf den gebauten stdio-Server:

{
  "mcpServers": {
    "echarts-chartpage": {
      "command": "node",
      "args": ["dist/mcp/server.js"]
    }
  }
}

Siehe examples/mcp-usage.md für Beispiele von Anfrage-Payloads.

Programmier-API

Öffentliche API-Oberfläche:

• generateChartPage

• recommendChartType

• validateChartInput

• validateChartPageRequest

• validateGeneratedHtml

• patchChartPage

• buildChartOption

• buildChartHtml

Laufzeitschemata werden ebenfalls exportiert:

• generateChartPageInputSchema

• patchChartPageChangesSchema

• patchChartPageInputSchema

• validateChartPageInputSchema

Eingabe- / Ausgabebeispiel

Eingabe:

{
  "title": "Traffic Source Mix",
  "goal": "composition",
  "theme": "light",
  "outputMode": "single_html",
  "data": [
    { "source": "Organic", "sessions": 4200 },
    { "source": "Paid", "sessions": 2100 },
    { "source": "Referral", "sessions": 1100 }
  ],
  "fields": {
    "x": "source",
    "y": "sessions",
    "category": "source"
  }
}

Ausgabezusammenfassung:

{
  "chartType": "donut",
  "warnings": [],
  "html": "<!doctype html>..."
}

Beispiele

Das Repository enthält:

• examples/inputs/line-chart.json

• examples/inputs/bar-chart.json

• examples/inputs/pie-chart.json

• examples/inputs/multi-series.json

• examples/inputs/patch-base.json

• examples/inputs/patch-update.json

• examples/cli-usage.md

• examples/mcp-usage.md

Generieren Sie alle Beispiel-HTML-Dateien mit:

npm run examples:generate

Generierte HTML-Dateien werden nach examples/generated/ geschrieben.

Agenten-Skill

Dieses Repository enthält auch einen wiederverwendbaren Codex-artigen Skill für Agenten, die den MCP-Server konsistent aufrufen müssen:

• skills/echarts-chartpage-mcp/SKILL.md

Er dokumentiert:

• wann dieser MCP ausgelöst werden soll

• wie man zwischen Empfehlen / Validieren / Generieren / Patchen wählt

• strukturierte Aufrufregeln

• Few-Shot-Beispiele für das Modell-Prompting

Installieren Sie den gebündelten Skill mit folgendem Befehl in das lokale Codex-Skill-Verzeichnis:

npm run build
npm run skill:install

Architektur

Projektlayout:

src/
  core/
    chart-recommender.ts
    option-builder.ts
    html-builder.ts
    validator.ts
    patcher.ts
    generator.ts
  cli/
    index.ts
    commands/
  mcp/
    server.ts
  schemas/
  types/
  utils/

Designregeln:

• Kernlogik wird über alle Schnittstellen hinweg geteilt

• Ausgabe ist kontrolliert und deterministisch

• keine willkürlichen Formatter-Funktionen werden akzeptiert

• nur Diagrammtypen aus der Whitelist werden ausgegeben

• Dataset + Encode wird bevorzugt, wo praktikabel

Siehe auch:

• docs/ARCHITECTURE.md

• docs/BACKGROUND.md

• docs/PUBLISHING.md

• SECURITY.md

Entwicklungsbefehle

npm install
npm run lint
npm run typecheck
npm run test
npm run build
npm run examples:generate

Build-Befehl

npm run build

Ausgaben werden nach dist/ geschrieben.

Test-Befehl

npm run test

Veröffentlichungshinweise

Vor der Veröffentlichung:

1. Repository-URLs in package.json aktualisieren.

2. Sicherstellen, dass das npm-Konto daqiang901003 auf der Veröffentlichungsmaschine authentifiziert ist.

3. CHANGELOG.md überprüfen.

4. npm run verify ausführen.

5. Mit npm publish veröffentlichen.

Das Paket ist konfiguriert mit:

• exports

• generierten .d.ts

• bin

• files

• ESM-First-Ausgabe mit CommonJS-Kompatibilität

Roadmap

• reichhaltigere, ranking-spezifische Sortierkontrollen

• dashboard-orientierte Multi-Panel-HTML-Vorlagen

• mehr Heuristiken für Diagrammempfehlungen

• konfigurierbare Design-Presets

• reichhaltigere MCP-Metadaten und Traces

FAQ

Führt dies willkürlichen Benutzer-JavaScript-Code aus?

Nein. Der Generator akzeptiert keine willkürlichen Formatter-Funktionen, Skriptfragmente oder benutzerdefinierte JS-Injektionen.

Warum greift manche Eingabe auf table zurück?

Der Builder verwendet eine konservative Whitelist. Wenn Zuordnungen oder Datentypen nicht mit einer kontrollierten Diagrammausgabe kompatibel sind, erfolgt ein Fallback auf eine stabile Tabellendarstellung.

Benötigt das generierte HTML einen Build-Schritt?

Nein. Es ist eine einzelne HTML-Datei, die direkt im Browser geöffnet werden kann.

Kann ich einen Diagrammtyp erzwingen?

Ja. Setzen Sie chartType in der Eingabe. Wenn das angeforderte Diagramm nicht mit der Datenzuordnung kompatibel ist, werden Validierungswarnungen zurückgegeben und die Generierung kann auf table zurückfallen.

Sicherheit

• keine willkürliche Skriptinjektion

• keine willkürliche externe JS-Injektion über das feste ECharts-CDN hinaus

• keine Injektion von Formatter-Funktionen

• kontrollierte HTML-Vorlagenform

• Schema-Validierung vor der Generierung

Dieses Projekt ist für vertrauenswürdige strukturierte Datenpipelines gedacht. Wenn Sie nicht vertrauenswürdige Eingaben von externen Benutzern akzeptieren, validieren und bereinigen Sie diese ebenfalls an Ihrer eigenen Grenze.

Die vollständige Repository-Richtlinie finden Sie unter SECURITY.md.

ECharts-Integrationshinweis

Dieses Projekt verwendet ECharts an zwei Stellen:

• der Quellcode hängt vom offiziellen echarts npm-Paket für die typisierte Optionsgenerierung ab

• das generierte HTML verwendet die feste Apache ECharts CDN-Laufzeit, sodass die Ausgabedatei ohne Bundler direkt in einem Browser geöffnet werden kann

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

MIT. Siehe LICENSE.