ECharts ChartPage

echarts-chartpage es un kit de herramientas de TypeScript que convierte datos JSON estructurados, objetivos de visualización y asignaciones de campos en páginas de gráficos HTML seguras y ejecutables, impulsadas por Apache ECharts.

Se distribuye como:

• un paquete npm para uso programático

• una CLI para automatización local

• un servidor MCP para flujos de trabajo de agentes

El proyecto está diseñado para una salida determinista, generación de opciones controlada, validación sólida y mantenibilidad de código abierto público.

Características

• Generación de páginas de gráficos HTML completas en un solo archivo con el CDN de Apache ECharts incluido

• Dependencia del paquete npm oficial echarts en el código fuente para tipos y corrección de integración

• Aceptación de datos estructurados además de entradas de goal, theme y asignación de campos

• Recomendación de tipos de gráficos seguros a partir de una lista blanca controlada

• Construcción de opciones de ECharts controladas sin inyección arbitraria de formateadores JS

• Validación de esquemas, asignaciones de campos, compatibilidad de gráficos y conceptos básicos de HTML generado

• Corrección de especificaciones de gráficos existentes y regeneración de la salida

• Reutilización de un núcleo compartido en la API de npm, CLI y servidor MCP

• Entrega con pruebas, CI, ejemplos, documentos de contribución y empaquetado listo para su publicación

Objetivos admitidos

• trend

• compare

• composition

• distribution

• ranking

• correlation

Tipos de gráficos admitidos

• line

• bar

• stacked_bar

• pie

• donut

• scatter

• area

• table

Instalación

npm install echarts-chartpage

Para desarrollo local:

npm install

Inicio rápido

CLI

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

API de npm

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);

Servidor MCP

Construya primero, luego inicie el servidor stdio:

npm run build
npm run mcp:start

Modelo de entrada

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";
};

Salida

generateChartPage() devuelve:

• especificación normalizada

• tipo de gráfico resuelto

• advertencias

• opción de ECharts controlada o null para alternativa de tabla

• HTML ejecutable completo

Uso de la CLI

El nombre del binario de la CLI es echarts-chartpage.

generate

Generar una página HTML única a partir de una entrada JSON:

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

recommend

Recomendar un tipo de gráfico:

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

validate

Validar la entrada y, opcionalmente, validar el HTML generado:

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

patch

Corregir una especificación de gráfico base y regenerar el HTML:

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

Uso de MCP

El servidor expone estas herramientas:

• recommend_chart_type

• generate_chart_page

• validate_chart_page

• patch_chart_page

Todas las entradas y salidas de las herramientas son JSON estructurado. Una configuración típica de cliente MCP apunta al servidor stdio compilado:

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

Consulte examples/mcp-usage.md para ver ejemplos de carga útil de solicitudes.

API de programación

Superficie de la API pública:

• generateChartPage

• recommendChartType

• validateChartInput

• validateChartPageRequest

• validateGeneratedHtml

• patchChartPage

• buildChartOption

• buildChartHtml

Los esquemas de tiempo de ejecución también se exportan:

• generateChartPageInputSchema

• patchChartPageChangesSchema

• patchChartPageInputSchema

• validateChartPageInputSchema

Ejemplo de entrada / salida

Entrada:

{
  "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"
  }
}

Resumen de salida:

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

Ejemplos

El repositorio incluye:

• 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

Genere todos los archivos HTML de ejemplo con:

npm run examples:generate

Los archivos HTML generados se escriben en examples/generated/.

Habilidad del agente

Este repositorio también incluye una habilidad reutilizable estilo Codex para agentes que necesitan llamar al servidor MCP de manera consistente:

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

Documenta:

• cuándo activar este MCP

• cómo elegir entre recomendar / validar / generar / corregir

• reglas de llamada estructuradas

• ejemplos de pocos disparos para la incitación del modelo

Instale la habilidad incluida en el directorio de habilidades local de Codex con:

npm run build
npm run skill:install

Arquitectura

Diseño del proyecto:

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/

Reglas de diseño:

• la lógica central se comparte en todas las interfaces

• la salida es controlada y determinista

• no se aceptan funciones de formateo arbitrarias

• solo se emiten tipos de gráficos de la lista blanca

• se prefiere dataset + encode cuando sea práctico

Véase también:

• docs/ARCHITECTURE.md

• docs/BACKGROUND.md

• docs/PUBLISHING.md

• SECURITY.md

Comandos de desarrollo

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

Comando de compilación

npm run build

Las salidas se emiten a dist/.

Comando de prueba

npm run test

Notas de publicación

Antes de publicar:

1. Actualice las URL del repositorio en package.json.

2. Asegúrese de que la cuenta de npm daqiang901003 esté autenticada en la máquina de publicación.

3. Revise el CHANGELOG.md.

4. Ejecute npm run verify.

5. Publique con npm publish.

El paquete está configurado con:

• exports

• .d.ts generado

• bin

• files

• Salida orientada a ESM con compatibilidad con CommonJS

Hoja de ruta

• controles de ordenación específicos para clasificaciones más ricos

• plantillas HTML multipanel orientadas a paneles de control

• más heurísticas de recomendación de gráficos

• ajustes preestablecidos de diseño configurables

• metadatos y trazas de MCP más ricos

Preguntas frecuentes

¿Esto ejecuta JavaScript de usuario arbitrario?

No. El generador no acepta funciones de formateo arbitrarias, fragmentos de script ni inyección de JS personalizada.

¿Por qué algunas entradas recurren a table?

El constructor utiliza una lista blanca conservadora. Si las asignaciones o los tipos de datos son incompatibles con una salida de gráfico controlada, recurre a una representación de tabla estable.

¿El HTML generado necesita un paso de compilación?

No. Es un archivo HTML único destinado a abrirse directamente en el navegador.

¿Puedo forzar un tipo de gráfico?

Sí. Establezca chartType en la entrada. Si el gráfico solicitado es incompatible con la asignación de datos, se devuelven advertencias de validación y la generación puede recurrir a table.

Seguridad

• sin inyección de script arbitraria

• sin inyección de JS externo arbitrario más allá del CDN fijo de ECharts

• sin inyección de función de formateo

• forma de plantilla HTML controlada

• validación de esquema antes de la generación

Este proyecto está destinado a tuberías de datos estructurados de confianza. Si acepta entradas no confiables de usuarios externos, valídelas y desinféctelas también en su propio límite.

Para conocer la política completa del repositorio, consulte SECURITY.md.

Nota de integración de ECharts

Este proyecto utiliza ECharts en dos lugares:

• el código fuente depende del paquete npm oficial echarts para la generación de opciones tipadas

• el HTML generado utiliza el tiempo de ejecución del CDN de Apache ECharts fijo para que el archivo de salida pueda abrirse directamente en un navegador sin un empaquetador

Contribución

Consulte CONTRIBUTING.md.

Licencia

MIT. Consulte LICENSE.