diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..7cd4256 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,210 @@ +# Flint：AI 時代のための可視化言語 + +[English](README.md) | [简体中文](README.zh-CN.md) | **日本語** + +[![npm: flint-chart](https://img.shields.io/npm/v/flint-chart.svg?label=npm%3A%20flint-chart)](https://www.npmjs.com/package/flint-chart) +[![npm: flint-chart-mcp](https://img.shields.io/npm/v/flint-chart-mcp.svg?label=npm%3A%20flint-chart-mcp)](https://www.npmjs.com/package/flint-chart-mcp) +[![CI](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +**こちらをご覧ください：** [**Flint プロジェクトサイト**](https://microsoft.github.io/flint-chart/) | [**MCP サーバーガイド**](https://microsoft.github.io/flint-chart/#/mcp) | [**中国語ホームページ**](https://microsoft.github.io/flint-chart/#/zh) + +Flint は、**AI エージェントがシンプルで人間にも編集しやすいチャート仕様から、 +表現力豊かで洗練された可視化を作成できる**ようにする可視化中間言語です。 +エージェントや開発者がスケール、軸、間隔、ラベル、レイアウトなどの +冗長なチャート設定を細かく調整する代わりに、Flint コンパイラーが +データ、セマンティック型、チャートタイプ、エンコーディングから最適な +チャート設定を導出します。その結果、エージェントが安定して生成でき、 +人間が直接編集でき、複数のバックエンドがネイティブな +[Vega-Lite](https://vega.github.io/vega-lite/)、 +[ECharts](https://echarts.apache.org/)、または +[Chart.js](https://www.chartjs.org/) の仕様としてレンダリングできる、簡潔なチャート仕様が得られます。 + +このリポジトリには、主に 2 つのコンポーネントがあります： + +- **`flint-chart`**：同じ Flint 入力を Vega-Lite、ECharts、または + Chart.js の仕様にコンパイルする JavaScript/TypeScript ライブラリです。 +- **`flint-chart-mcp`**：エージェントがチャットやコーディング環境から + 直接チャートを作成、検証、レンダリングできる MCP サーバーです。 + +

+ Flint で作成されたチャート群：棒グラフ、折れ線グラフ、散布図、ヒートマップ、ドーナツグラフ、レーダーチャート、ストリームグラフ、箱ひげ図、グループ化棒グラフ、ローズチャート、サンキーダイアグラム、ツリーマップを Vega-Lite、ECharts、Chart.js でレンダリング。 +

+ +## 機能 + + +- **セマンティックなチャート仕様。** Flint は `Rank`、`Temperature`、 + `Price`、`Country` など、70 種類以上のセマンティック型を使用して各フィールドの意味を表します。 +- **自動レイアウト。** Flint はデータのカーディナリティ、チャート設計、 + キャンバスの制約に応じて、サイズ、間隔、ラベル、マーク、凡例を調整します。 +- **複数のバックエンド。** 1 つの入力から + [Vega-Lite](https://vega.github.io/vega-lite/)、 + [ECharts](https://echarts.apache.org/)、 + [Chart.js](https://www.chartjs.org/) を通じて 30 種類以上のチャートタイプにコンパイルでき、今後さらに追加される予定です。 +- **エージェント向けのチャート作成。** MCP サーバーはエージェントに Flint のツールと + チャート作成ガイドを提供し、テンプレートの選択、検証、MCP 対応クライアントでの + インタラクティブなチャートビューの表示を可能にします。 + +## 更新情報 + +- **2026 年 7 月 19 日** — Flint 0.3.0 では、チャートタイプの切り替えと + チャートプロパティの直接編集ができる動的チャートウィジェットが追加されました。([v0.3.0](https://github.com/microsoft/flint-chart/releases/tag/0.3.0)) +- **2026 年 7 月 15 日** — Flint 0.2.2 では、コンパクトなドッジモードと + グループ化バイオリンプロットのレイアウトが追加されました。 +- **2026 年 7 月 13 日** — Flint 0.2.1 では、チャートプロパティの検証と + バックエンド間の一貫性が改善されました。([v0.2.1](https://github.com/microsoft/flint-chart/releases/tag/0.2.1)) + +すべてのリリースノートについては、[変更履歴](CHANGELOG.md)をご覧ください。 + + +

+ Flint が簡潔なチャート仕様を Vega-Lite 仕様とレンダリング済みのヒートマップ可視化にコンパイルしている様子。 +
+ Flint は簡潔なチャート仕様を、バックエンドネイティブの仕様とレンダリング済みの可視化に変換します。 +

+ +## インストール + +```bash +# Use Flint in your JavaScript/TypeScript codebase +npm install flint-chart + +# For agents and MCP clients +npx -y flint-chart-mcp +``` + +

Python パッケージは今後リリース予定です。現在の Python ポートは、このリポジトリでソースのみのプレビューとして提供されています。

+ +## Flint をライブラリとして使用する + +すべてのバックエンドが同じ `ChartAssemblyInput` を受け取り、対象 +ライブラリのネイティブな仕様オブジェクトを返します。 + +```ts +import { assembleVegaLite } from 'flint-chart'; + +const spec = assembleVegaLite({ + data: { values: myData }, + semantic_types: { weight: 'Quantity', mpg: 'Quantity', origin: 'Country' }, + chart_spec: { + chartType: 'Scatter Plot', + encodings: { x: { field: 'weight' }, y: { field: 'mpg' }, color: { field: 'origin' } }, + baseSize: { width: 400, height: 300 }, + }, +}); +// → a ready-to-render Vega-Lite spec +``` + +入力形式を変えずにバックエンドを切り替えられます： + +```ts +import { assembleECharts, assembleChartjs } from 'flint-chart'; + +const echartsOption = assembleECharts(input); +const chartjsConfig = assembleChartjs(input); +``` + +ライブラリのその他の例については、[API リファレンス](docs/api-reference.md)、 +[バックエンドリファレンス](docs/reference-vegalite.md)、 +[ライブエディター](https://microsoft.github.io/flint-chart/#/editor)をご覧ください。 + +## Flint を MCP サーバーとして使用する + +質問を始めた同じ会話内でエージェントにチャートを作成させたい場合は、 +`flint-chart-mcp` を [Model Context Protocol](https://modelcontextprotocol.io/) +サーバーとしてインストールします。インタラクティブなチャートビューを開いたり、 +静的な PNG/SVG 出力やバックエンドネイティブのチャート仕様を生成したりできます。 + +セットアップについては、まず +[Flint MCP プロジェクトページ](https://microsoft.github.io/flint-chart/#/mcp)をご覧ください。 +クライアント設定、使用例、より詳しいリファレンスへのリンクが掲載されています。 + +

+ Flint Chart を MCP App として使用するエージェントチャット。グループ化棒グラフのプレビューとチャートオプションが表示されています。 +

+ +MCP 呼び出しでは、`data.values` として行を直接埋め込むことも、 +`data.url` からローカルの JSON、CSV、TSV ファイルを読み込むこともできます。 +MCP を使わないエージェントワークフローでは、独立した +[エージェントスキル](agent-skills/flint-chart-author/SKILL.md)を使用してください。 + +## リポジトリ概要 + +``` +flint-chart/ +├── packages/ +│ ├── flint-js/ npm package `flint-chart` (TypeScript) +│ │ └── src/ +│ │ ├── core/ semantics, layout, decisions, shared types +│ │ ├── vegalite/ Vega-Lite backend +│ │ ├── echarts/ ECharts backend +│ │ ├── chartjs/ Chart.js backend +│ │ └── test-data/ fixtures + generators (drive tests and the gallery) +│ ├── flint-py/ Python port preview (package to be released) +│ └── flint-mcp/ npm package `flint-chart-mcp` (MCP render server) +├── site/ Vite + React demo: landing, gallery, editor, docs +├── agent-skills/ fallback copy of the MCP-served agent skill +├── shared/test-data/ JSON fixtures shared across JS + Python +└── docs/ architecture and design documents +``` + +### ドキュメント + +[プロジェクトサイト](https://microsoft.github.io/flint-chart/)は、使用例、 +ライブエディター、概念ドキュメントへの主要な入口です。ソースレベルの +リファレンスについては、[API リファレンス](docs/api-reference.md)、 +[Flint MCP プロジェクトページ](https://microsoft.github.io/flint-chart/#/mcp)、 +[開発ガイド](docs/DEVELOPMENT.md)からご覧ください。各リリースの主な変更は +[変更履歴](CHANGELOG.md)に記載されています。 + +--- + +## コントリビューション + +コントリビューションを歓迎します！[.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) +と[開発ガイド](docs/DEVELOPMENT.md)をご覧ください。 + +```bash +git clone https://github.com/microsoft/flint-chart +cd flint-chart +npm install # root workspaces: packages/flint-js + flint-mcp + site + +npm run typecheck # typecheck packages/flint-js + packages/flint-mcp +npm run test # Vitest (packages/flint-js + packages/flint-mcp) +npm run build # build packages/flint-js + packages/flint-mcp +npm run site # demo site (gallery + editor) at http://localhost:5274/ +``` + +Node 18 以降が必要です。デモサイトでは `flint-chart` が +`packages/flint-js/src` にエイリアスされるため、ライブラリへの編集は +`dist/` を再ビルドしなくてもギャラリーとエディターにホットリロードされます。 + +特に、新しい +[チャートテンプレート](docs/adding-a-chart-template.md)や +[レンダリングバックエンド](docs/adding-a-backend.md)のコントリビューションを歓迎します。 + +このプロジェクトは +[Microsoft オープンソース行動規範](.github/CODE_OF_CONDUCT.md)を採用しています。 +セキュリティ上の問題を報告するには [SECURITY.md](.github/SECURITY.md) をご覧ください。 + +## コントリビューター + +Flint は [Microsoft Research](https://www.microsoft.com/en-us/research/) と +中国人民大学の [IDEAS Lab](https://ideas-lab.net/) が共同で開発しています。 +ぜひご参加ください。詳しくは[コントリビューション](#コントリビューション)をご覧ください。 + +Flint について説明する研究論文は近日公開予定です。 + +## 商標 + +このプロジェクトには、プロジェクト、製品、サービスの商標またはロゴが含まれる場合があります。 +Microsoft の商標またはロゴの許可された使用には、 +[Microsoft の商標およびブランドガイドライン](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)を遵守する必要があります。 +このプロジェクトの変更版で Microsoft の商標またはロゴを使用する場合、 +混同を招いたり、Microsoft の後援を示唆したりしてはなりません。 +第三者の商標またはロゴの使用には、それぞれの第三者のポリシーが適用されます。 + +## ライセンス + +[MIT](LICENSE) © Microsoft Corporation diff --git a/README.md b/README.md index 00d1081..3ad3c2e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Flint: A Visualization Language for the AI Era +**English** | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) + [![npm: flint-chart](https://img.shields.io/npm/v/flint-chart.svg?label=npm%3A%20flint-chart)](https://www.npmjs.com/package/flint-chart) [![npm: flint-chart-mcp](https://img.shields.io/npm/v/flint-chart-mcp.svg?label=npm%3A%20flint-chart-mcp)](https://www.npmjs.com/package/flint-chart-mcp) [![CI](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml) diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..12701ec --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,203 @@ +# Flint：AI 时代的可视化语言 + +[English](README.md) | **简体中文** | [日本語](README.ja.md) + +[![npm: flint-chart](https://img.shields.io/npm/v/flint-chart.svg?label=npm%3A%20flint-chart)](https://www.npmjs.com/package/flint-chart) +[![npm: flint-chart-mcp](https://img.shields.io/npm/v/flint-chart-mcp.svg?label=npm%3A%20flint-chart-mcp)](https://www.npmjs.com/package/flint-chart-mcp) +[![CI](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +**请访问：** [**Flint 项目网站**](https://microsoft.github.io/flint-chart/) | [**MCP 服务器指南**](https://microsoft.github.io/flint-chart/#/mcp) | [**中文主页**](https://microsoft.github.io/flint-chart/#/zh) + +Flint 是一种可视化中间语言，让 **AI 智能体能够根据简单且便于人工编辑的图表规范， +创建表现力丰富、精美完善的可视化图表**。 +智能体或开发者无需再逐项调整比例尺、坐标轴、间距、标签和布局等冗长的图表配置 +细节；Flint 编译器会根据数据、语义类型、图表类型和 +编码推导出优化后的图表设置。最终得到的紧凑图表规范既能由智能体 +可靠生成，也可由人工直接编辑，还能通过多个后端渲染为原生 +[Vega-Lite](https://vega.github.io/vega-lite/)、 +[ECharts](https://echarts.apache.org/) 或 +[Chart.js](https://www.chartjs.org/) 规范。 + +本仓库包含两个主要组件： + +- **`flint-chart`**：一个 JavaScript/TypeScript 库，可将同一份 + Flint 输入编译为 Vega-Lite、ECharts 或 Chart.js 规范。 +- **`flint-chart-mcp`**：一个 MCP 服务器，让智能体能够直接在聊天或编码 + 环境中创建、验证和渲染图表。 + +

+ 由 Flint 生成的一组图表：条形图、折线图、散点图、热力图、环形图、雷达图、河流图、箱线图、分组条形图、玫瑰图、桑基图和矩形树图，并分别通过 Vega-Lite、ECharts 和 Chart.js 渲染。 +

+ +## 功能 + + +- **语义化图表规范。** Flint 使用 70 多种语义类型来描述每个字段的含义， + 例如 `Rank`、`Temperature`、`Price` 或 `Country`。 +- **自动布局。** Flint 会根据数据基数、图表设计和画布约束， + 自动调整尺寸、间距、标签、标记和图例。 +- **多个后端。** 使用同一份输入，即可通过 + [Vega-Lite](https://vega.github.io/vega-lite/)、 + [ECharts](https://echarts.apache.org/) 和 + [Chart.js](https://www.chartjs.org/) 编译出 30 多种图表类型，未来还会支持更多后端。 +- **面向智能体的图表创作。** MCP 服务器为智能体提供 Flint 工具和 + 图表指导，使其可以选择模板、完成验证，并在支持 MCP 的客户端中打开 + 交互式图表视图。 + +## 更新 + +- **2026 年 7 月 19 日** — Flint 0.3.0 新增动态图表小组件，可切换图表 + 类型并直接编辑图表属性。([v0.3.0](https://github.com/microsoft/flint-chart/releases/tag/0.3.0)) +- **2026 年 7 月 15 日** — Flint 0.2.2 新增紧凑的错开模式和分组小提琴图 + 布局。 +- **2026 年 7 月 13 日** — Flint 0.2.1 改进了图表属性验证和后端 + 一致性。([v0.2.1](https://github.com/microsoft/flint-chart/releases/tag/0.2.1)) + +完整的发布说明请参阅[变更日志](CHANGELOG.md)。 + + +

+ Flint 将紧凑的图表规范编译为 Vega-Lite 规范和渲染后的热力图可视化。 +
+ Flint 将紧凑的图表规范转换为后端原生规范和渲染后的可视化图表。 +

+ +## 安装 + +```bash +# Use Flint in your JavaScript/TypeScript codebase +npm install flint-chart + +# For agents and MCP clients +npx -y flint-chart-mcp +``` + +

Python 包尚未发布。仓库中的当前 Python 移植版本仅提供源码预览。

+ +## 将 Flint 用作库 + +每个后端都接受同一种 `ChartAssemblyInput`，并返回目标 +库的原生规范对象。 + +```ts +import { assembleVegaLite } from 'flint-chart'; + +const spec = assembleVegaLite({ + data: { values: myData }, + semantic_types: { weight: 'Quantity', mpg: 'Quantity', origin: 'Country' }, + chart_spec: { + chartType: 'Scatter Plot', + encodings: { x: { field: 'weight' }, y: { field: 'mpg' }, color: { field: 'origin' } }, + baseSize: { width: 400, height: 300 }, + }, +}); +// → a ready-to-render Vega-Lite spec +``` + +无需改变输入结构即可切换后端： + +```ts +import { assembleECharts, assembleChartjs } from 'flint-chart'; + +const echartsOption = assembleECharts(input); +const chartjsConfig = assembleChartjs(input); +``` + +更多库示例请参阅 [API 参考](docs/api-reference.md)、[后端参考](docs/reference-vegalite.md) +和[在线编辑器](https://microsoft.github.io/flint-chart/#/editor)。 + +## 将 Flint 用作 MCP 服务器 + +如果希望智能体在发起问题的同一个对话中创建图表，可将 `flint-chart-mcp` +安装为 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。 +它可以打开交互式图表视图、返回静态 PNG/SVG 输出，或生成后端原生图表规范。 + +配置时请先查看 +[Flint MCP 项目页面](https://microsoft.github.io/flint-chart/#/mcp)，其中包含 +客户端配置、使用示例以及更深入参考资料的链接。 + +

+ 智能体聊天界面展示作为 MCP App 运行的 Flint Chart，其中包含分组条形图预览和图表选项。 +

+ +MCP 调用可以通过 `data.values` 直接嵌入数据行，也可以通过 `data.url` +读取本地 JSON、CSV 或 TSV 文件。对于不使用 MCP 的智能体工作流， +请使用独立的[智能体技能](agent-skills/flint-chart-author/SKILL.md)。 + +## 仓库概览 + +``` +flint-chart/ +├── packages/ +│ ├── flint-js/ npm package `flint-chart` (TypeScript) +│ │ └── src/ +│ │ ├── core/ semantics, layout, decisions, shared types +│ │ ├── vegalite/ Vega-Lite backend +│ │ ├── echarts/ ECharts backend +│ │ ├── chartjs/ Chart.js backend +│ │ └── test-data/ fixtures + generators (drive tests and the gallery) +│ ├── flint-py/ Python port preview (package to be released) +│ └── flint-mcp/ npm package `flint-chart-mcp` (MCP render server) +├── site/ Vite + React demo: landing, gallery, editor, docs +├── agent-skills/ fallback copy of the MCP-served agent skill +├── shared/test-data/ JSON fixtures shared across JS + Python +└── docs/ architecture and design documents +``` + +### 文档 + +[项目网站](https://microsoft.github.io/flint-chart/)是示例、在线编辑器和概念文档的主要 +入口。若要查看源码级参考资料，请从 [API 参考](docs/api-reference.md)、 +[Flint MCP 项目页面](https://microsoft.github.io/flint-chart/#/mcp)或 +[开发指南](docs/DEVELOPMENT.md)开始。每个版本的重要变更请参阅 +[变更日志](CHANGELOG.md)。 + +--- + +## 参与贡献 + +欢迎贡献！请参阅 [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) +和[开发指南](docs/DEVELOPMENT.md)。 + +```bash +git clone https://github.com/microsoft/flint-chart +cd flint-chart +npm install # root workspaces: packages/flint-js + flint-mcp + site + +npm run typecheck # typecheck packages/flint-js + packages/flint-mcp +npm run test # Vitest (packages/flint-js + packages/flint-mcp) +npm run build # build packages/flint-js + packages/flint-mcp +npm run site # demo site (gallery + editor) at http://localhost:5274/ +``` + +需要 Node 18 或更高版本。演示网站会将 `flint-chart` 映射到 +`packages/flint-js/src`，因此库的编辑内容可在图库和编辑器中热更新， +无需重新构建 `dist/`。 + +我们尤其欢迎贡献新的 +[图表模板](docs/adding-a-chart-template.md)或新的 +[渲染后端](docs/adding-a-backend.md)。 + +本项目已采用 +[Microsoft 开源行为准则](.github/CODE_OF_CONDUCT.md)。安全漏洞请按照 +[SECURITY.md](.github/SECURITY.md) 中的说明报告。 + +## 贡献者 + +Flint 由 [Microsoft Research](https://www.microsoft.com/en-us/research/) +与中国人民大学 [IDEAS Lab](https://ideas-lab.net/) 合作开发。欢迎加入我们——请参阅[参与贡献](#参与贡献)。 + +介绍 Flint 的研究论文即将发布。 + +## 商标 + +本项目可能包含项目、产品或服务的商标或徽标。 +Microsoft 商标或徽标的授权使用必须遵守 +[Microsoft 商标和品牌指南](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 +在本项目的修改版本中使用 Microsoft 商标或徽标时，不得造成混淆或暗示获得 Microsoft 赞助。 +任何第三方商标或徽标的使用均须遵守相应第三方的政策。 + +## 许可证 + +[MIT](LICENSE) © Microsoft Corporation