ECharts ChartPage

echarts-chartpage — это набор инструментов на TypeScript, который превращает структурированные JSON-данные, цели визуализации и сопоставления полей в безопасные, готовые к запуску HTML-страницы с графиками на базе Apache ECharts.

Поставляется в виде:

• npm-пакета для программного использования

• CLI для локальной автоматизации

• MCP-сервера для агентских рабочих процессов

Проект разработан для обеспечения детерминированного вывода, контролируемой генерации опций, строгой проверки и удобства сопровождения открытого исходного кода.

Возможности

• Генерация полноценных HTML-страниц с одним файлом, включая CDN Apache ECharts

• Использование официального npm-пакета echarts в исходном коде для корректности типов и интеграции

• Прием структурированных данных, а также ввод goal (цели), theme (темы) и сопоставления полей

• Рекомендация безопасных типов графиков из контролируемого «белого списка»

• Создание контролируемых опций ECharts без внедрения произвольных JS-форматтеров

• Проверка схемы, сопоставлений полей, совместимости графиков и основ сгенерированного HTML

• Исправление существующих спецификаций графиков и повторная генерация вывода

• Использование одного общего ядра для npm API, CLI и MCP-сервера

• Поставка с тестами, CI, примерами, документацией для участников и готовой к выпуску упаковкой

Поддерживаемые цели

• trend (тренд)

• compare (сравнение)

• composition (состав)

• distribution (распределение)

• ranking (ранжирование)

• correlation (корреляция)

Поддерживаемые типы графиков

• line (линейный)

• bar (столбчатый)

• stacked_bar (столбчатый с накоплением)

• pie (круговой)

• donut (кольцевой)

• scatter (точечный)

• area (область)

• table (таблица)

Установка

npm install echarts-chartpage

Для локальной разработки:

npm install

Быстрый старт

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-сервер

Сначала выполните сборку, затем запустите stdio-сервер:

npm run build
npm run mcp:start

Модель ввода

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

Вывод

generateChartPage() возвращает:

• нормализованную спецификацию

• разрешенный тип графика

• предупреждения

• контролируемую опцию ECharts или null для резервного варианта в виде таблицы

• готовый к запуску HTML

Использование CLI

Имя бинарного файла CLI — echarts-chartpage.

generate

Генерация одной HTML-страницы из JSON-ввода:

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

recommend

Рекомендация типа графика:

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

validate

Проверка ввода и (опционально) проверка сгенерированного HTML:

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

patch

Исправление базовой спецификации графика и повторная генерация HTML:

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

Использование MCP

Сервер предоставляет следующие инструменты:

• recommend_chart_type

• generate_chart_page

• validate_chart_page

• patch_chart_page

Все входные и выходные данные инструментов представляют собой структурированный JSON. Типичная конфигурация MCP-клиента указывает на собранный stdio-сервер:

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

Примеры полезной нагрузки запросов см. в examples/mcp-usage.md.

Программный API

Поверхность публичного API:

• generateChartPage

• recommendChartType

• validateChartInput

• validateChartPageRequest

• validateGeneratedHtml

• patchChartPage

• buildChartOption

• buildChartHtml

Схемы времени выполнения также экспортируются:

• generateChartPageInputSchema

• patchChartPageChangesSchema

• patchChartPageInputSchema

• validateChartPageInputSchema

Пример ввода / вывода

Ввод:

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

Сводка вывода:

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

Примеры

Репозиторий включает:

• 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

Сгенерируйте все примеры HTML-файлов с помощью:

npm run examples:generate

Сгенерированные HTML-файлы записываются в examples/generated/.

Навык агента

Этот репозиторий также включает переиспользуемый навык в стиле Codex для агентов, которым необходимо последовательно вызывать MCP-сервер:

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

В нем документировано:

• когда запускать этот MCP

• как выбирать между рекомендацией / проверкой / генерацией / исправлением

• правила структурированного вызова

• примеры few-shot для промптинга моделей

Установите входящий в комплект навык в локальный каталог навыков Codex с помощью:

npm run build
npm run skill:install

Архитектура

Структура проекта:

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/

Правила проектирования:

• основная логика общая для всех интерфейсов

• вывод контролируемый и детерминированный

• произвольные функции-форматтеры не принимаются

• генерируются только типы графиков из «белого списка»

• где это целесообразно, предпочтение отдается dataset + encode

См. также:

• docs/ARCHITECTURE.md

• docs/BACKGROUND.md

• docs/PUBLISHING.md

• SECURITY.md

Команды разработки

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

Команда сборки

npm run build

Результаты выводятся в dist/.

Команда тестирования

npm run test

Примечания по публикации

Перед публикацией:

1. Обновите URL-адреса репозитория в package.json.

2. Убедитесь, что учетная запись npm daqiang901003 аутентифицирована на машине публикации.

3. Просмотрите CHANGELOG.md.

4. Запустите npm run verify.

5. Опубликуйте с помощью npm publish.

Пакет настроен с использованием:

• exports

• сгенерированных .d.ts

• bin

• files

• ESM-первого вывода с совместимостью CommonJS

Дорожная карта

• более богатые элементы управления сортировкой для ранжирования

• ориентированные на дашборды многопанельные HTML-шаблоны

• больше эвристик для рекомендации графиков

• настраиваемые пресеты дизайна

• более богатые метаданные и трассировки MCP

Часто задаваемые вопросы

Выполняет ли это произвольный JavaScript пользователя?

Нет. Генератор не принимает произвольные функции-форматтеры, фрагменты скриптов или пользовательские JS-инъекции.

Почему некоторые входные данные возвращаются к table?

Сборщик использует консервативный «белый список». Если сопоставления или типы данных несовместимы с контролируемым выводом графика, он возвращается к стабильному отображению таблицы.

Нужен ли сгенерированному HTML этап сборки?

Нет. Это один HTML-файл, предназначенный для открытия непосредственно в браузере.

Могу ли я принудительно задать тип графика?

Да. Установите chartType во входных данных. Если запрошенный график несовместим с сопоставлением данных, будут возвращены предупреждения проверки, и генерация может вернуться к table.

Безопасность

• отсутствие произвольных инъекций скриптов

• отсутствие произвольных внешних JS-инъекций, кроме фиксированного CDN ECharts

• отсутствие инъекций функций-форматтеров

• контролируемая форма HTML-шаблона

• проверка схемы перед генерацией

Этот проект предназначен для доверенных конвейеров структурированных данных. Если вы принимаете недоверенные входные данные от внешних пользователей, проверяйте и очищайте их также на своей границе.

Полную политику репозитория см. в SECURITY.md.

Примечание по интеграции ECharts

Этот проект использует ECharts в двух местах:

• исходный код зависит от официального npm-пакета echarts для типизированной генерации опций

• сгенерированный HTML использует фиксированную среду выполнения Apache ECharts CDN, чтобы выходной файл можно было открыть непосредственно в браузере без сборщика

Участие в разработке

См. CONTRIBUTING.md.

Лицензия

MIT. См. LICENSE.