diff --git a/README.md b/README.md index 40b2276..a87832a 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,37 @@ # Liquid Protocol -**自然言語でダッシュボードを自由自在に。** +**Transform dashboards with natural language.** -AIドリブンUI生成のためのオープンソースプロトコル +Open-source protocol for AI-driven UI generation [![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) -[English](./docs/README.en.md) | 日本語 +English | [日本語](./docs/readmeLangs/README.ja.md) | [简体中文](./docs/readmeLangs/README.zh-CN.md) | [繁體中文](./docs/readmeLangs/README.zh-TW.md) | [Русский](./docs/readmeLangs/README.ru.md) | [Українська](./docs/readmeLangs/README.uk.md) | [فارسی](./docs/readmeLangs/README.fa.md) | [العربية](./docs/readmeLangs/README.ar.md) --- -## 一言で言うと +## In a Nutshell -**「交通費を除外して、月別の支出を棒グラフで見せて」** +**"Exclude transportation costs and show monthly expenses as a bar chart"** -こう言うだけで、ダッシュボードが自動で再構成されます。 +Just say this, and your dashboard automatically reconfigures itself.
| Before | After | |--------|-------| -| ![初期ダッシュボード](docs/images/dashboard-initial.png) | ![AI更新後](docs/images/dashboard-after-ai.png) | -| デフォルトのダッシュボード | 「交通費を除外して」と指示した後 | +| ![Initial Dashboard](docs/images/dashboard-initial.png) | ![After AI Update](docs/images/dashboard-after-ai.png) | +| Default dashboard | After saying "Exclude transportation" |
--- -## 30秒で試す +## Quick Start (30 seconds) ```bash npx create-next-liqueur-app my-dashboard @@ -40,176 +40,273 @@ cd my-dashboard npm run dev ``` -[http://localhost:3000](http://localhost:3000) を開いて、チャットで指示するだけ。 +Open [http://localhost:3000](http://localhost:3000) and start chatting. --- -## 目次 +## Table of Contents -- [Claude Artifacts / Gemini Canvas との違い](#claude-artifacts--gemini-canvas-との違い) -- [解決する問題](#解決する問題) -- [様々なアプリへの応用](#様々なアプリへの応用) -- [仕組み](#仕組み) -- [インストール](#インストール) -- [サンプルアプリ](#サンプルアプリ) -- [セキュリティ設計](#セキュリティ設計) -- [スキーマ仕様](#スキーマ仕様) -- [ロードマップ](#ロードマップ) +- [Why Liquid Protocol?](#why-liquid-protocol) +- [Comparison with Claude Artifacts / Gemini Canvas](#comparison-with-claude-artifacts--gemini-canvas) +- [Use Cases](#use-cases) +- [How It Works](#how-it-works) +- [Installation](#installation) +- [Developer Setup](#developer-setup) +- [Security Design](#security-design) +- [Schema Specification](#schema-specification) +- [Roadmap](#roadmap) --- -## Claude Artifacts / Gemini Canvas との違い +## Why Liquid Protocol? -[Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) や [Gemini Canvas](https://gemini.google/jp/overview/canvas/) を使ったことがありますか？ +### The Customization Dilemma -AI との会話でダッシュボードやコードを生成できる、素晴らしい機能です。 +Consider a budget tracking app. No matter which app you use, you'll always have requests like: -**Liquid Protocol は、この体験を「自分のアプリ」で実現するためのプロトコルです。** +> - "Exclude transportation costs - my company reimburses those" +> - "Family card purchases should be separate - I get reimbursed" +> - "Tag all spending during my trip as 'travel'" +> - "I hate red - make it blue and black" -| 機能 | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | -|------|:---------------:|:-------------:|:-------------------:| -| AI による UI 生成 | ✅ | ✅ | ✅ | -| 自分のアプリに組み込み | ❌ | ❌ | **✅** | -| 自分のデータベース接続 | ❌ | ❌ | **✅** | -| Row-Level Security | ❌ | ❌ | **✅** | -| コード実行リスク | ⚠️ サンドボックス | ⚠️ サンドボックス | **✅ なし** | -| オープンソース | ❌ | ❌ | **✅ MIT** | -| AI プロバイダー選択 | Claude のみ | Gemini のみ | **自由** | +**Current solutions:** -### 要するに +| Approach | Example | Problem | +|:---------|:--------|:--------| +| Build everything yourself | Notion, Spreadsheets | Customization becomes the goal. You lose focus | +| Add more settings | Traditional apps | Settings screens become complex. "Too much freedom" | -``` -Claude Artifacts / Gemini Canvas - → 素晴らしい。でも、それは「彼らのアプリ」の中だけ。 +### Liquid's Solution -Liquid Protocol - → 同じ体験を「あなたのアプリ」で。 - あなたのデータベース、あなたのユーザーに。 -``` +**Just say what you want.** ---- +``` +User: "Exclude transportation costs" + ↓ +AI regenerates the dashboard structure + ↓ +Filters, charts, and layouts update automatically +``` -## 解決する問題 +No more hunting through settings screens. -### カスタマイズの二極化 +--- -家計簿アプリを例に考えてみましょう。どのアプリを使っても、必ずこんな要望が出てきます： +## Comparison with Claude Artifacts / Gemini Canvas -> - 「交通費は会社持ちだから除外して」 -> - 「家族カードは返金されるから別会計で」 -> - 「旅行中の支出には『旅行』タグをつけて」 -> - 「赤が嫌いだから青と黒にして」 +Have you used [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) or [Gemini Canvas](https://gemini.google/overview/canvas/)? -**現状の解決策：** +They're amazing features that let you generate dashboards and code through AI conversations. -| アプローチ | 例 | 問題点 | -|:----------|:---|:-------| -| 全部自分で作る | Notion, スプレッドシート | カスタマイズが目的化。本来の作業から脱線 | -| 設定項目を増やす | 従来のアプリ | 設定画面が複雑化。「自由すぎる不自由」 | +**Liquid Protocol brings this experience to YOUR app.** -### Liquid の解決策 +| Feature | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|---------|:---------------:|:-------------:|:-------------------:| +| AI-powered UI generation | ✅ | ✅ | ✅ | +| Embed in your own app | ❌ | ❌ | **✅** | +| Connect your own database | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| Code execution risk | ⚠️ Sandboxed | ⚠️ Sandboxed | **✅ None** | +| Open Source | ❌ | ❌ | **✅ MIT** | +| AI provider choice | Claude only | Gemini only | **Any** | -**言葉で伝えるだけ。** +### In Summary ``` -ユーザー: 「交通費は除外して」 - ↓ -AI がダッシュボードの構造を再生成 - ↓ -フィルタ・グラフ・レイアウトが自動更新 -``` +Claude Artifacts / Gemini Canvas + → Amazing. But only within THEIR apps. -設定画面を探し回る必要はありません。 +Liquid Protocol + → The same experience in YOUR app. + Your database, your users. +``` --- -## 様々なアプリへの応用 +## Use Cases -今は家計簿で実証していますが、この技術はあらゆるアプリに適用できます： +We're demonstrating with a budget app, but this technology applies to any application: -| アプリ | 従来の問題 | Liquid による解決 | -|:-------|:----------|:-----------------| -| **Slack / Discord** | 通知設定が複雑 | 「重要な会話だけ通知して」 | -| **証券アプリ** | ダッシュボードが固定 | 「テック株だけ円グラフで」 | -| **Twitter / SNS** | アルゴリズムが不透明 | 「政治関連を非表示に」 | -| **プロジェクト管理** | Jira の設定地獄 | 「今週の自分のタスクだけ」 | +| Application | Traditional Problem | Liquid Solution | +|:------------|:-------------------|:----------------| +| **Slack / Discord** | Complex notification settings | "Only notify me for important conversations" | +| **Stock Trading** | Fixed dashboards | "Show only tech stocks in a pie chart" | +| **Twitter / SNS** | Opaque algorithm | "Hide political content" | +| **Project Management** | Jira settings hell | "Show only my tasks this week" | -**将来、この技術はソフトウェアの標準になる。** +**This technology will become the software standard.** --- -## 仕組み +## How It Works ``` ┌─────────────────────────────────────────────────────────────┐ -│ ユーザー: 「交通費を除外して、棒グラフで見せて」 │ +│ User: "Exclude transportation, show as bar chart" │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ AI (Claude / GPT / Gemini) │ +│ AI (Claude / GPT / Gemini / DeepSeek / GLM) │ │ │ -│ ⚠️ JSON スキーマのみ出力。JS/SQL は生成しない │ +│ ⚠️ Outputs JSON schema ONLY. No JS/SQL generation │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ @liqueur/protocol │ │ │ -│ ✅ スキーマ検証: 未知フィールドは即拒否 │ -│ ✅ TypeScript + Rust で二重検証 │ +│ ✅ Schema validation: Unknown fields rejected immediately │ +│ ✅ TypeScript + Rust dual validation │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ @liqueur/db-adapter │ │ │ │ 🔒 Row-Level Security │ -│ 🔒 SQL インジェクション防止 │ +│ 🔒 SQL injection prevention │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ @liqueur/react │ │ │ -│ 📊 チャート・テーブル・レイアウトを自動レンダリング │ +│ 📊 Auto-render charts, tables, and layouts │ └─────────────────────────────────────────────────────────────┘ ``` --- -## インストール +## Installation -### 用途別 +### By Use Case ```bash -# スキーマ定義のみ +# Schema definitions only npm install @liqueur/protocol -# React UI 追加 +# Add React UI npm install @liqueur/protocol @liqueur/react -# フルスタック（AI + DB） +# Full stack (AI + Database) npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter ``` -### パッケージ一覧 +### Packages -| パッケージ | 役割 | -|:----------|:-----| -| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | スキーマ型定義 & バリデーション | -| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI コンポーネント | -| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI プロバイダー統合 | -| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma クエリ実行 | -| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | スキーマ永続化 | -| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | プロジェクト作成 CLI | +| Package | Purpose | +|:--------|:--------| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Schema types & validation | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI components | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI provider integration | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma query execution | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Schema persistence | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | Project scaffolding CLI | --- -## サンプルアプリ +## Developer Setup + +### Option 1: Quick Start with CLI + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# Configure your AI provider +cp .env.example .env +# Edit .env with your API key + +npm run dev +``` + +### Option 2: Add to Existing Project + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### Environment Variables + +When using `@liqueur/ai-provider`, configure environment variables for your chosen AI provider: + +```bash +# .env or .env.local + +# Choose provider: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# Models: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# Models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# Models: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# Models: deepseek-chat, deepseek-coder + +# ─── GLM (Zhipu AI) ─────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# Models: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### Basic Usage + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// Create provider from environment variables +const provider = ProviderFactory.createFromEnv(); + +// Generate schema from natural language +const schema = await provider.generateSchema( + "Show monthly expenses as a bar chart", + databaseMetadata +); + +// Render the dashboard + +``` + +### Example: Next.js API Route + +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +### Sample Applications -| サンプル | 説明 | 実行 | -|:--------|:-----|:-----| -| [家計簿アプリ](./examples/household-budget) | AI チャット付きフル機能 | `cd examples/household-budget && pnpm dev` | -| [Playground](./examples/playground) | シンプルなテスト環境 | `cd examples/playground && pnpm dev` | +| Sample | Description | Run | +|:-------|:------------|:----| +| [Household Budget](./examples/household-budget) | Full-featured with AI chat | `cd examples/household-budget && pnpm dev` | +| [Playground](./examples/playground) | Simple test environment | `cd examples/playground && pnpm dev` | -### ローカルで実行 +### Run from Source ```bash git clone https://github.com/clearclown/liqueur.git @@ -217,42 +314,42 @@ cd liqueur pnpm install && pnpm build cd examples/household-budget -cp .env.example .env # API キー設定 +cp .env.example .env # Configure API keys pnpm dev ``` --- -## セキュリティ設計 +## Security Design -### なぜ AI に JavaScript を書かせないのか？ +### Why Not Let AI Write JavaScript? -| 方式 | リスク | -|:-----|:-------| -| AI が JS/SQL 生成 | XSS、SQL インジェクション、任意コード実行 | -| **Liquid: JSON のみ** | 実行コードなし。スキーマ外は拒否 | +| Approach | Risk | +|:---------|:-----| +| AI generates JS/SQL | XSS, SQL injection, arbitrary code execution | +| **Liquid: JSON only** | No executable code. Unknown fields rejected | -### 3層の防御 +### Three Layers of Defense -1. **AI 出力制限** — JSON スキーマのみ。コード生成なし -2. **スキーマ検証** — 未知フィールドは即拒否（Fail Fast） -3. **Row-Level Security** — ユーザーは自分のデータのみアクセス可能 +1. **AI Output Restriction** — JSON schema only. No code generation +2. **Schema Validation** — Unknown fields rejected immediately (Fail Fast) +3. **Row-Level Security** — Users can only access their own data ``` -❌ AI が生成しないもの +❌ What AI DOES NOT generate - JavaScript - SQL - - シェルコマンド + - Shell commands -✅ AI が生成するもの - - 検証済み JSON スキーマのみ +✅ What AI generates + - Validated JSON schema only ``` --- -## スキーマ仕様 +## Schema Specification -### 基本構造 +### Basic Structure ```typescript interface LiquidViewSchema { @@ -263,18 +360,18 @@ interface LiquidViewSchema { } ``` -### コンポーネント +### Components -- `chart` — 棒グラフ、折れ線、円グラフ、面グラフ -- `table` — データテーブル（ソート対応） +- `chart` — Bar, line, pie, area charts +- `table` — Data table (sortable) ### DataSource ```typescript interface DataSource { - resource: string; // テーブル名 - filters?: Filter[]; // WHERE 条件 - aggregation?: { // GROUP BY + 集計 + resource: string; // Table name + filters?: Filter[]; // WHERE conditions + aggregation?: { // GROUP BY + aggregation type: 'sum' | 'count' | 'avg' | 'min' | 'max'; field: string; by: string; @@ -284,7 +381,7 @@ interface DataSource { } ``` -### 例：交通費を除外した支出 +### Example: Expenses excluding transportation ```typescript const schema: LiquidViewSchema = { @@ -294,7 +391,7 @@ const schema: LiquidViewSchema = { { type: 'chart', variant: 'pie', - title: '今月の支出内訳', + title: 'Monthly Expenses', data_source: 'expenses' } ], @@ -303,7 +400,7 @@ const schema: LiquidViewSchema = { resource: 'transactions', filters: [ { field: 'type', op: 'eq', value: 'EXPENSE' }, - { field: 'category', op: 'neq', value: '交通費' } // ← 除外 + { field: 'category', op: 'neq', value: 'Transportation' } // ← Excluded ], aggregation: { type: 'sum', field: 'amount', by: 'category' } } @@ -311,22 +408,22 @@ const schema: LiquidViewSchema = { }; ``` -詳細は [@liqueur/protocol](./packages/protocol) を参照。 +See [@liqueur/protocol](./packages/protocol) for details. --- -## ロードマップ +## Roadmap -- [x] Phase 1: コアプロトコル & React コンポーネント -- [x] Phase 2: AI プロバイダー統合 -- [x] Phase 3: サンプルアプリ（家計簿） -- [ ] Phase 4: コンポーネント追加（カレンダー、マップ等） -- [ ] Phase 5: リアルタイム協調編集 -- [ ] Phase 6: プラグインシステム +- [x] Phase 1: Core protocol & React components +- [x] Phase 2: AI provider integration +- [x] Phase 3: Sample app (household budget) +- [ ] Phase 4: Additional components (calendar, map, etc.) +- [ ] Phase 5: Real-time collaborative editing +- [ ] Phase 6: Plugin system --- -## 開発 +## Development ```bash pnpm install @@ -334,11 +431,11 @@ pnpm build pnpm test ``` -詳細は [CONTRIBUTING.md](./CONTRIBUTING.md) を参照。 +See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. --- -## ライセンス +## License [MIT](LICENSE) @@ -348,7 +445,7 @@ pnpm test **Liquid Protocol** -ユーザーが設定と格闘する時代を終わらせる +End the era of users fighting with settings [GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) diff --git a/docs/README.en.md b/docs/README.en.md deleted file mode 100644 index 97cd837..0000000 --- a/docs/README.en.md +++ /dev/null @@ -1,170 +0,0 @@ -
- -# Liquid Protocol - -**Transform dashboards with natural language. AI-driven UI generation protocol.** - -[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) -[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) - -English | [日本語](../README.md) - -
- ---- - -## Why Liquid Protocol? - -### The Problem: Customization Dilemma - -Consider a household budget app. There are countless budget/expense management apps out there. - -Yet, no matter which app you use, you'll always have requests like: - -> - "Exclude transportation costs - my company reimburses those" -> - "Family card purchases should be separate - I get reimbursed" -> - "Tag all spending during my trip as 'travel'" -> - "I hate red - make it blue and black" -> - "Show me a bar chart instead of pie chart" - -**Current solutions fall into two categories:** - -| Approach | Example | Problem | -|----------|---------|---------| -| **Build it yourself** | Notion, Spreadsheets | Customization becomes the goal. You lose sight of actual "budget management" | -| **Add more settings** | Traditional apps | Settings screens become complex. "Freedom becomes imprisonment" | - -### The Solution: Restructure dashboards with natural language - -**Liquid Protocol** solves this problem fundamentally. - -``` -User: "Exclude transportation costs, tag travel period expenses as 'travel'" - ↓ -AI regenerates the dashboard structure itself - ↓ -Filters, charts, and layouts update automatically -``` - ---- - -## This isn't just about budget apps - -We're demonstrating with a budget app now, but this technology applies to **any application**: - -| Application | Traditional Problem | Liquid Solution | -|-------------|---------------------|-----------------| -| **Slack / Discord** | Complex notification settings | "Only notify me for important conversations" | -| **Stock Trading** | Fixed dashboards | "Show only tech stocks in a pie chart" | -| **Twitter / SNS** | Opaque timeline algorithms | "Hide political content" for your own feed | -| **Project Management** | Jira/Asana settings hell | "Show only my tasks this week" | - -**This technology will become the standard.** Users shouldn't fight with settings screens - they should just say what they want. - ---- - -## How it works: AI + JSON Schema + Security - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ User Request │ -│ "Exclude transportation, show monthly expenses as bar chart" │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ AI (Claude / GPT / Gemini) │ -│ │ -│ ⚠️ Important: AI outputs JSON schema ONLY │ -│ Never generates JavaScript or SQL │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ @liqueur/protocol │ -│ │ -│ ✅ Schema validation: Unknown fields rejected immediately │ -│ ✅ Type-safe: Double validation with TypeScript + Rust │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ @liqueur/db-adapter │ -│ │ -│ 🔒 Row-Level Security: Users can only access their own data │ -│ 🔒 SQL injection prevention: ORM only, no raw SQL │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ @liqueur/react │ -│ │ -│ 📊 Auto-render charts, tables, and layouts │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Why not let AI write JavaScript? - -| Approach | Risk | -|----------|------| -| AI generates JS/SQL | XSS, SQL injection, arbitrary code execution | -| **Liquid: JSON only** | Unknown fields rejected. No executable code | - ---- - -## Quick Start - -### Try in 30 seconds - -```bash -npx create-next-liqueur-app my-dashboard -cd my-dashboard -npm run dev -``` - -Open [http://localhost:3000](http://localhost:3000) and just chat. - ---- - -## Installation - -```bash -# Schema definition only (types & validation) -npm install @liqueur/protocol - -# React UI components -npm install @liqueur/protocol @liqueur/react - -# Full stack (AI + Database) -npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter -``` - -### Packages - -| Package | Purpose | npm | -|---------|---------|-----| -| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Schema types & validation | ![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square) | -| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI components (Chart, Table) | ![npm](https://img.shields.io/npm/v/@liqueur/react?style=flat-square) | -| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI provider integration | ![npm](https://img.shields.io/npm/v/@liqueur/ai-provider?style=flat-square) | -| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma query execution | ![npm](https://img.shields.io/npm/v/@liqueur/db-adapter?style=flat-square) | -| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Schema persistence | ![npm](https://img.shields.io/npm/v/@liqueur/artifact-store?style=flat-square) | -| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | Project scaffolding CLI | ![npm](https://img.shields.io/npm/v/create-next-liqueur-app?style=flat-square) | - ---- - -## Examples - -| Example | Description | Run | -|---------|-------------|-----| -| [Household Budget](../examples/household-budget) | Full-featured app with AI chat | `cd examples/household-budget && pnpm dev` | -| [Playground](../examples/playground) | Simple schema testing | `cd examples/playground && pnpm dev` | - ---- - -## License - -[MIT](../LICENSE) - ---- - -
- -**Liquid Protocol** - End the era of users fighting with settings - -
diff --git a/docs/readmeLangs/README.ar.md b/docs/readmeLangs/README.ar.md new file mode 100644 index 0000000..92bff78 --- /dev/null +++ b/docs/readmeLangs/README.ar.md @@ -0,0 +1,368 @@ +
+ +# Liquid Protocol + +**حوّل لوحات المعلومات باستخدام اللغة الطبيعية.** + +بروتوكول مفتوح المصدر لتوليد واجهات المستخدم بالذكاء الاصطناعي + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [Русский](./README.ru.md) | [Українська](./README.uk.md) | [فارسی](./README.fa.md) | العربية + +
+ +--- + +
+ +## باختصار + +**"استبعد تكاليف النقل واعرض المصروفات الشهرية كرسم بياني شريطي"** + +فقط قل هذا، وستتم إعادة تكوين لوحة المعلومات تلقائياً. + +
+ +
+ +| قبل | بعد | +|-----|-----| +| ![لوحة المعلومات الأولية](../images/dashboard-initial.png) | ![بعد تحديث الذكاء الاصطناعي](../images/dashboard-after-ai.png) | +| لوحة المعلومات الافتراضية | بعد قول "استبعد النقل" | + +
+ +--- + +
+ +## البدء السريع (30 ثانية) + +
+ +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +
+ +افتح [http://localhost:3000](http://localhost:3000) وابدأ المحادثة. + +--- + +## جدول المحتويات + +- [لماذا Liquid Protocol؟](#لماذا-liquid-protocol) +- [المقارنة مع Claude Artifacts / Gemini Canvas](#المقارنة-مع-claude-artifacts--gemini-canvas) +- [حالات الاستخدام](#حالات-الاستخدام) +- [كيف يعمل](#كيف-يعمل) +- [التثبيت](#التثبيت) +- [إعداد المطورين](#إعداد-المطورين) +- [تصميم الأمان](#تصميم-الأمان) +- [خارطة الطريق](#خارطة-الطريق) + +--- + +## لماذا Liquid Protocol؟ + +### معضلة التخصيص + +خذ تطبيق تتبع الميزانية كمثال. أياً كان التطبيق الذي تستخدمه، ستكون لديك دائماً طلبات مثل: + +> - "استبعد تكاليف النقل - الشركة تسددها" +> - "مشتريات البطاقة العائلية يجب أن تكون منفصلة - أحصل على استرداد" +> - "ضع علامة 'سفر' على جميع النفقات أثناء رحلتي" +> - "لا أحب الأحمر - اجعله أزرق وأسود" + +**الحلول الحالية:** + +| النهج | مثال | المشكلة | +|:------|:-----|:--------| +| بناء كل شيء بنفسك | Notion، جداول البيانات | التخصيص يصبح الهدف. تفقد التركيز | +| إضافة المزيد من الإعدادات | التطبيقات التقليدية | شاشات الإعدادات تصبح معقدة. "حرية مفرطة" | + +### حل Liquid + +**فقط قل ما تريد.** + +``` +المستخدم: "استبعد تكاليف النقل" + ↓ +الذكاء الاصطناعي يعيد توليد هيكل لوحة المعلومات + ↓ +الفلاتر والرسوم البيانية والتخطيطات تُحدَّث تلقائياً +``` + +لا مزيد من البحث في شاشات الإعدادات. + +--- + +## المقارنة مع Claude Artifacts / Gemini Canvas + +هل استخدمت [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) أو [Gemini Canvas](https://gemini.google/overview/canvas/)؟ + +إنها ميزات رائعة تتيح لك توليد لوحات المعلومات والكود من خلال المحادثة مع الذكاء الاصطناعي. + +**Liquid Protocol يجلب هذه التجربة إلى تطبيقك.** + +| الميزة | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|--------|:---------------:|:-------------:|:-------------------:| +| توليد UI بالذكاء الاصطناعي | ✅ | ✅ | ✅ | +| التضمين في تطبيقك الخاص | ❌ | ❌ | **✅** | +| الاتصال بقاعدة بياناتك | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| مخاطر تنفيذ الكود | ⚠️ صندوق رمل | ⚠️ صندوق رمل | **✅ لا شيء** | +| مفتوح المصدر | ❌ | ❌ | **✅ MIT** | +| اختيار مزود الذكاء الاصطناعي | Claude فقط | Gemini فقط | **أي مزود** | + +### الخلاصة + +``` +Claude Artifacts / Gemini Canvas + → رائع. لكن فقط داخل تطبيقاتهم. + +Liquid Protocol + → نفس التجربة في تطبيقك. + قاعدة بياناتك، مستخدميك. +``` + +--- + +## حالات الاستخدام + +نحن نعرض باستخدام تطبيق الميزانية، لكن هذه التقنية تنطبق على أي تطبيق: + +| التطبيق | المشكلة التقليدية | حل Liquid | +|:--------|:-----------------|:----------| +| **Slack / Discord** | إعدادات إشعارات معقدة | "أخبرني فقط عن المحادثات المهمة" | +| **تداول الأسهم** | لوحات معلومات ثابتة | "اعرض فقط أسهم التكنولوجيا في رسم دائري" | +| **Twitter / SNS** | خوارزمية غير شفافة | "أخفِ المحتوى السياسي" | +| **إدارة المشاريع** | جحيم إعدادات Jira | "اعرض فقط مهامي لهذا الأسبوع" | + +**هذه التقنية ستصبح معياراً للبرمجيات.** + +--- + +## التثبيت + +### حسب الاستخدام + +
+ +```bash +# تعريفات Schema فقط +npm install @liqueur/protocol + +# إضافة React UI +npm install @liqueur/protocol @liqueur/react + +# Full stack (AI + قاعدة البيانات) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +
+ +### الحزم + +| الحزمة | الغرض | +|:-------|:------| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | أنواع Schema والتحقق | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | مكونات UI | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | تكامل مزود الذكاء الاصطناعي | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | تنفيذ استعلامات Prisma | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | حفظ Schema | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | CLI لإنشاء المشروع | + +--- + +## إعداد المطورين + +### الطريقة 1: البدء السريع مع CLI + +
+ +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# تكوين مزود الذكاء الاصطناعي +cp .env.example .env +# حرر .env وأضف مفتاح API + +npm run dev +``` + +
+ +### الطريقة 2: الإضافة إلى مشروع موجود + +
+ +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +
+ +### متغيرات البيئة + +عند استخدام `@liqueur/ai-provider`، قم بتكوين متغيرات البيئة لمزود الذكاء الاصطناعي الذي اخترته: + +
+ +```bash +# .env أو .env.local + +# اختر المزود: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# النماذج: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# النماذج: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# النماذج: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# النماذج: deepseek-chat, deepseek-coder + +# ─── GLM (Zhipu AI) ─────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# النماذج: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +
+ +### الاستخدام الأساسي + +
+ +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// إنشاء Provider من متغيرات البيئة +const provider = ProviderFactory.createFromEnv(); + +// توليد Schema من اللغة الطبيعية +const schema = await provider.generateSchema( + "اعرض المصروفات الشهرية كرسم بياني شريطي", + databaseMetadata +); + +// عرض لوحة المعلومات + +``` + +
+ +### مثال: Next.js API Route + +
+ +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +
+ +### التطبيقات النموذجية + +| النموذج | الوصف | التشغيل | +|:--------|:------|:--------| +| [تتبع الميزانية](../../examples/household-budget) | كامل الميزات مع دردشة AI | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | بيئة اختبار بسيطة | `cd examples/playground && pnpm dev` | + +### التشغيل من الكود المصدري + +
+ +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # إعداد مفاتيح API +pnpm dev +``` + +
+ +--- + +## تصميم الأمان + +### لماذا لا نسمح للذكاء الاصطناعي بكتابة JavaScript؟ + +| النهج | المخاطر | +|:------|:--------| +| الذكاء الاصطناعي يولد JS/SQL | XSS، حقن SQL، تنفيذ كود عشوائي | +| **Liquid: JSON فقط** | لا كود قابل للتنفيذ. الحقول غير المعروفة ترفض | + +### ثلاث طبقات من الدفاع + +١. **تقييد مخرجات الذكاء الاصطناعي** — Schema JSON فقط. لا توليد كود +٢. **التحقق من Schema** — الحقول غير المعروفة ترفض فوراً (Fail Fast) +٣. **Row-Level Security** — المستخدمون يمكنهم الوصول فقط إلى بياناتهم + +--- + +## خارطة الطريق + +- [x] المرحلة 1: البروتوكول الأساسي ومكونات React +- [x] المرحلة 2: تكامل مزودي الذكاء الاصطناعي +- [x] المرحلة 3: تطبيق نموذجي (الميزانية) +- [ ] المرحلة 4: مكونات إضافية (التقويم، الخريطة، إلخ.) +- [ ] المرحلة 5: التحرير التعاوني في الوقت الفعلي +- [ ] المرحلة 6: نظام الإضافات + +--- + +## الترخيص + +[MIT](../../LICENSE) + +--- + +
+ +
+ +**Liquid Protocol** + +إنهاء عصر صراع المستخدمين مع الإعدادات + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.fa.md b/docs/readmeLangs/README.fa.md new file mode 100644 index 0000000..d996491 --- /dev/null +++ b/docs/readmeLangs/README.fa.md @@ -0,0 +1,368 @@ +
+ +# Liquid Protocol + +**داشبوردها را با زبان طبیعی تغییر دهید.** + +پروتکل متن‌باز برای تولید UI با هوش مصنوعی + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [Русский](./README.ru.md) | [Українська](./README.uk.md) | فارسی | [العربية](./README.ar.md) + +
+ +--- + +
+ +## خلاصه + +**«هزینه‌های حمل و نقل را حذف کن و هزینه‌های ماهانه را به صورت نمودار میله‌ای نشان بده»** + +فقط این را بگویید و داشبورد شما به طور خودکار پیکربندی می‌شود. + +
+ +
+ +| قبل | بعد | +|-----|-----| +| ![داشبورد اولیه](../images/dashboard-initial.png) | ![پس از به‌روزرسانی AI](../images/dashboard-after-ai.png) | +| داشبورد پیش‌فرض | پس از گفتن «حذف حمل و نقل» | + +
+ +--- + +
+ +## شروع سریع (۳۰ ثانیه) + +
+ +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +
+ +[http://localhost:3000](http://localhost:3000) را باز کنید و شروع به گفتگو کنید. + +--- + +## فهرست مطالب + +- [چرا Liquid Protocol؟](#چرا-liquid-protocol) +- [مقایسه با Claude Artifacts / Gemini Canvas](#مقایسه-با-claude-artifacts--gemini-canvas) +- [موارد استفاده](#موارد-استفاده) +- [نحوه کار](#نحوه-کار) +- [نصب](#نصب) +- [راه‌اندازی برای توسعه‌دهندگان](#راهاندازی-برای-توسعهدهندگان) +- [طراحی امنیتی](#طراحی-امنیتی) +- [نقشه راه](#نقشه-راه) + +--- + +## چرا Liquid Protocol؟ + +### معضل سفارشی‌سازی + +یک برنامه مدیریت بودجه را در نظر بگیرید. هر برنامه‌ای که استفاده کنید، همیشه درخواست‌هایی مانند این خواهید داشت: + +> - «هزینه حمل و نقل را حذف کن - شرکت آن را پرداخت می‌کند» +> - «خریدهای کارت خانواده باید جدا باشد - بازپرداخت می‌شود» +> - «همه هزینه‌های سفر را با برچسب "سفر" مشخص کن» +> - «من قرمز را دوست ندارم - آبی و سیاه کن» + +**راه‌حل‌های فعلی:** + +| رویکرد | مثال | مشکل | +|:-------|:-----|:-----| +| همه چیز را خودتان بسازید | Notion، صفحات گسترده | سفارشی‌سازی هدف می‌شود. تمرکز از دست می‌رود | +| تنظیمات بیشتر اضافه کنید | برنامه‌های سنتی | صفحات تنظیمات پیچیده می‌شود. «آزادی بیش از حد» | + +### راه‌حل Liquid + +**فقط بگویید چه می‌خواهید.** + +``` +کاربر: «هزینه حمل و نقل را حذف کن» + ↓ +AI ساختار داشبورد را بازتولید می‌کند + ↓ +فیلترها، نمودارها و چیدمان‌ها به طور خودکار به‌روز می‌شوند +``` + +دیگر نیازی به جستجو در صفحات تنظیمات نیست. + +--- + +## مقایسه با Claude Artifacts / Gemini Canvas + +آیا از [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) یا [Gemini Canvas](https://gemini.google/overview/canvas/) استفاده کرده‌اید؟ + +آن‌ها ویژگی‌های شگفت‌انگیزی هستند که به شما اجازه می‌دهند داشبوردها و کد را از طریق مکالمه با AI تولید کنید. + +**Liquid Protocol این تجربه را به برنامه شما می‌آورد.** + +| ویژگی | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|-------|:---------------:|:-------------:|:-------------------:| +| تولید UI با AI | ✅ | ✅ | ✅ | +| جاسازی در برنامه خودتان | ❌ | ❌ | **✅** | +| اتصال به پایگاه داده خودتان | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| ریسک اجرای کد | ⚠️ سندباکس | ⚠️ سندباکس | **✅ هیچ** | +| متن‌باز | ❌ | ❌ | **✅ MIT** | +| انتخاب ارائه‌دهنده AI | فقط Claude | فقط Gemini | **هر کدام** | + +### خلاصه + +``` +Claude Artifacts / Gemini Canvas + → شگفت‌انگیز. اما فقط در برنامه‌های آن‌ها. + +Liquid Protocol + → همان تجربه در برنامه شما. + پایگاه داده شما، کاربران شما. +``` + +--- + +## موارد استفاده + +ما با یک برنامه بودجه نمایش می‌دهیم، اما این فناوری برای هر برنامه‌ای کاربرد دارد: + +| برنامه | مشکل سنتی | راه‌حل Liquid | +|:-------|:----------|:-------------| +| **Slack / Discord** | تنظیمات پیچیده اعلان | «فقط برای مکالمات مهم اعلان بده» | +| **معاملات سهام** | داشبوردهای ثابت | «فقط سهام فناوری را در نمودار دایره‌ای نشان بده» | +| **Twitter / SNS** | الگوریتم نامشخص | «محتوای سیاسی را پنهان کن» | +| **مدیریت پروژه** | جهنم تنظیمات Jira | «فقط وظایف این هفته من را نشان بده» | + +**این فناوری به استاندارد نرم‌افزار تبدیل خواهد شد.** + +--- + +## نصب + +### بر اساس کاربرد + +
+ +```bash +# فقط تعاریف اسکیما +npm install @liqueur/protocol + +# اضافه کردن React UI +npm install @liqueur/protocol @liqueur/react + +# فول استک (AI + پایگاه داده) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +
+ +### پکیج‌ها + +| پکیج | کاربرد | +|:-----|:-------| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | تایپ‌های اسکیما و اعتبارسنجی | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | کامپوننت‌های UI | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | یکپارچه‌سازی ارائه‌دهنده AI | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | اجرای کوئری Prisma | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | ذخیره‌سازی اسکیما | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | CLI ساخت پروژه | + +--- + +## راه‌اندازی برای توسعه‌دهندگان + +### روش ۱: شروع سریع با CLI + +
+ +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# پیکربندی ارائه‌دهنده AI +cp .env.example .env +# فایل .env را ویرایش کنید و API key را اضافه کنید + +npm run dev +``` + +
+ +### روش ۲: افزودن به پروژه موجود + +
+ +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +
+ +### متغیرهای محیطی + +هنگام استفاده از `@liqueur/ai-provider`، متغیرهای محیطی را برای ارائه‌دهنده AI انتخابی پیکربندی کنید: + +
+ +```bash +# .env یا .env.local + +# انتخاب ارائه‌دهنده: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# مدل‌ها: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# مدل‌ها: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# مدل‌ها: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# مدل‌ها: deepseek-chat, deepseek-coder + +# ─── GLM (Zhipu AI) ─────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# مدل‌ها: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +
+ +### استفاده پایه + +
+ +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// ساخت Provider از متغیرهای محیطی +const provider = ProviderFactory.createFromEnv(); + +// تولید اسکیما از زبان طبیعی +const schema = await provider.generateSchema( + "هزینه‌های ماهانه را به صورت نمودار میله‌ای نشان بده", + databaseMetadata +); + +// رندر داشبورد + +``` + +
+ +### مثال: Next.js API Route + +
+ +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +
+ +### برنامه‌های نمونه + +| نمونه | توضیحات | اجرا | +|:------|:--------|:-----| +| [مدیریت بودجه](../../examples/household-budget) | کامل با چت AI | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | محیط تست ساده | `cd examples/playground && pnpm dev` | + +### اجرا از کد منبع + +
+ +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # پیکربندی کلیدهای API +pnpm dev +``` + +
+ +--- + +## طراحی امنیتی + +### چرا به AI اجازه نوشتن JavaScript نمی‌دهیم؟ + +| رویکرد | ریسک | +|:-------|:-----| +| AI کد JS/SQL تولید می‌کند | XSS، تزریق SQL، اجرای کد دلخواه | +| **Liquid: فقط JSON** | کد اجرایی وجود ندارد. فیلدهای ناشناخته رد می‌شوند | + +### سه لایه دفاعی + +۱. **محدودیت خروجی AI** — فقط اسکیمای JSON. بدون تولید کد +۲. **اعتبارسنجی اسکیما** — فیلدهای ناشناخته فوراً رد می‌شوند (Fail Fast) +۳. **Row-Level Security** — کاربران فقط می‌توانند به داده‌های خود دسترسی داشته باشند + +--- + +## نقشه راه + +- [x] فاز ۱: پروتکل اصلی و کامپوننت‌های React +- [x] فاز ۲: یکپارچه‌سازی ارائه‌دهنده AI +- [x] فاز ۳: برنامه نمونه (بودجه) +- [ ] فاز ۴: کامپوننت‌های اضافی (تقویم، نقشه و غیره) +- [ ] فاز ۵: ویرایش مشترک بلادرنگ +- [ ] فاز ۶: سیستم پلاگین + +--- + +## مجوز + +[MIT](../../LICENSE) + +--- + +
+ +
+ +**Liquid Protocol** + +پایان دادن به دوران جنگیدن کاربران با تنظیمات + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.ja.md b/docs/readmeLangs/README.ja.md new file mode 100644 index 0000000..0ac2be3 --- /dev/null +++ b/docs/readmeLangs/README.ja.md @@ -0,0 +1,408 @@ +
+ +# Liquid Protocol + +**自然言語でダッシュボードを自由自在に。** + +AIドリブンUI生成のためのオープンソースプロトコル + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | 日本語 | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [Русский](./README.ru.md) | [Українська](./README.uk.md) | [فارسی](./README.fa.md) | [العربية](./README.ar.md) + +
+ +--- + +## 一言で言うと + +**「交通費を除外して、月別の支出を棒グラフで見せて」** + +こう言うだけで、ダッシュボードが自動で再構成されます。 + +
+ +| Before | After | +|--------|-------| +| ![初期ダッシュボード](../images/dashboard-initial.png) | ![AI更新後](../images/dashboard-after-ai.png) | +| デフォルトのダッシュボード | 「交通費を除外して」と指示した後 | + +
+ +--- + +## 30秒で試す + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +[http://localhost:3000](http://localhost:3000) を開いて、チャットで指示するだけ。 + +--- + +## 目次 + +- [なぜ Liquid Protocol?](#なぜ-liquid-protocol) +- [Claude Artifacts / Gemini Canvas との違い](#claude-artifacts--gemini-canvas-との違い) +- [様々なアプリへの応用](#様々なアプリへの応用) +- [仕組み](#仕組み) +- [インストール](#インストール) +- [開発者向けセットアップ](#開発者向けセットアップ) +- [セキュリティ設計](#セキュリティ設計) +- [スキーマ仕様](#スキーマ仕様) +- [ロードマップ](#ロードマップ) + +--- + +## なぜ Liquid Protocol? + +### カスタマイズの二極化 + +家計簿アプリを例に考えてみましょう。どのアプリを使っても、必ずこんな要望が出てきます： + +> - 「交通費は会社持ちだから除外して」 +> - 「家族カードは返金されるから別会計で」 +> - 「旅行中の支出には『旅行』タグをつけて」 +> - 「赤が嫌いだから青と黒にして」 + +**現状の解決策：** + +| アプローチ | 例 | 問題点 | +|:----------|:---|:-------| +| 全部自分で作る | Notion, スプレッドシート | カスタマイズが目的化。本来の作業から脱線 | +| 設定項目を増やす | 従来のアプリ | 設定画面が複雑化。「自由すぎる不自由」 | + +### Liquid の解決策 + +**言葉で伝えるだけ。** + +``` +ユーザー: 「交通費は除外して」 + ↓ +AI がダッシュボードの構造を再生成 + ↓ +フィルタ・グラフ・レイアウトが自動更新 +``` + +設定画面を探し回る必要はありません。 + +--- + +## Claude Artifacts / Gemini Canvas との違い + +[Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) や [Gemini Canvas](https://gemini.google/jp/overview/canvas/) を使ったことがありますか？ + +AI との会話でダッシュボードやコードを生成できる、素晴らしい機能です。 + +**Liquid Protocol は、この体験を「自分のアプリ」で実現するためのプロトコルです。** + +| 機能 | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|------|:---------------:|:-------------:|:-------------------:| +| AI による UI 生成 | ✅ | ✅ | ✅ | +| 自分のアプリに組み込み | ❌ | ❌ | **✅** | +| 自分のデータベース接続 | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| コード実行リスク | ⚠️ サンドボックス | ⚠️ サンドボックス | **✅ なし** | +| オープンソース | ❌ | ❌ | **✅ MIT** | +| AI プロバイダー選択 | Claude のみ | Gemini のみ | **自由** | + +### 要するに + +``` +Claude Artifacts / Gemini Canvas + → 素晴らしい。でも、それは「彼らのアプリ」の中だけ。 + +Liquid Protocol + → 同じ体験を「あなたのアプリ」で。 + あなたのデータベース、あなたのユーザーに。 +``` + +--- + +## 様々なアプリへの応用 + +今は家計簿で実証していますが、この技術はあらゆるアプリに適用できます： + +| アプリ | 従来の問題 | Liquid による解決 | +|:-------|:----------|:-----------------| +| **Slack / Discord** | 通知設定が複雑 | 「重要な会話だけ通知して」 | +| **証券アプリ** | ダッシュボードが固定 | 「テック株だけ円グラフで」 | +| **Twitter / SNS** | アルゴリズムが不透明 | 「政治関連を非表示に」 | +| **プロジェクト管理** | Jira の設定地獄 | 「今週の自分のタスクだけ」 | + +**将来、この技術はソフトウェアの標準になる。** + +--- + +## 仕組み + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ユーザー: 「交通費を除外して、棒グラフで見せて」 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ AI (Claude / GPT / Gemini / DeepSeek / GLM) │ +│ │ +│ ⚠️ JSON スキーマのみ出力。JS/SQL は生成しない │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/protocol │ +│ │ +│ ✅ スキーマ検証: 未知フィールドは即拒否 │ +│ ✅ TypeScript + Rust で二重検証 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/db-adapter │ +│ │ +│ 🔒 Row-Level Security │ +│ 🔒 SQL インジェクション防止 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/react │ +│ │ +│ 📊 チャート・テーブル・レイアウトを自動レンダリング │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## インストール + +### 用途別 + +```bash +# スキーマ定義のみ +npm install @liqueur/protocol + +# React UI 追加 +npm install @liqueur/protocol @liqueur/react + +# フルスタック（AI + DB） +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +### パッケージ一覧 + +| パッケージ | 役割 | +|:----------|:-----| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | スキーマ型定義 & バリデーション | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI コンポーネント | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI プロバイダー統合 | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma クエリ実行 | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | スキーマ永続化 | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | プロジェクト作成 CLI | + +--- + +## 開発者向けセットアップ + +### 方法1: CLI でクイックスタート + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# AI プロバイダーを設定 +cp .env.example .env +# .env を編集して API キーを設定 + +npm run dev +``` + +### 方法2: 既存プロジェクトに追加 + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### 環境変数 + +`@liqueur/ai-provider` を使用する場合、選択した AI プロバイダーの環境変数を設定します： + +```bash +# .env または .env.local + +# プロバイダー選択: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# モデル: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# モデル: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# モデル: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# モデル: deepseek-chat, deepseek-coder + +# ─── GLM (智谱 AI) ──────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# モデル: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### 基本的な使い方 + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// 環境変数からプロバイダーを作成 +const provider = ProviderFactory.createFromEnv(); + +// 自然言語からスキーマを生成 +const schema = await provider.generateSchema( + "月別の支出を棒グラフで見せて", + databaseMetadata +); + +// ダッシュボードをレンダリング + +``` + +### サンプルアプリ + +| サンプル | 説明 | 実行 | +|:--------|:-----|:-----| +| [家計簿アプリ](../../examples/household-budget) | AI チャット付きフル機能 | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | シンプルなテスト環境 | `cd examples/playground && pnpm dev` | + +### ソースから実行 + +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # API キー設定 +pnpm dev +``` + +--- + +## セキュリティ設計 + +### なぜ AI に JavaScript を書かせないのか？ + +| 方式 | リスク | +|:-----|:-------| +| AI が JS/SQL 生成 | XSS、SQL インジェクション、任意コード実行 | +| **Liquid: JSON のみ** | 実行コードなし。スキーマ外は拒否 | + +### 3層の防御 + +1. **AI 出力制限** — JSON スキーマのみ。コード生成なし +2. **スキーマ検証** — 未知フィールドは即拒否（Fail Fast） +3. **Row-Level Security** — ユーザーは自分のデータのみアクセス可能 + +``` +❌ AI が生成しないもの + - JavaScript + - SQL + - シェルコマンド + +✅ AI が生成するもの + - 検証済み JSON スキーマのみ +``` + +--- + +## スキーマ仕様 + +### 基本構造 + +```typescript +interface LiquidViewSchema { + version: '1.0'; + layout: Layout; + components: Component[]; + data_sources: Record; +} +``` + +### コンポーネント + +- `chart` — 棒グラフ、折れ線、円グラフ、面グラフ +- `table` — データテーブル（ソート対応） + +### DataSource + +```typescript +interface DataSource { + resource: string; // テーブル名 + filters?: Filter[]; // WHERE 条件 + aggregation?: { // GROUP BY + 集計 + type: 'sum' | 'count' | 'avg' | 'min' | 'max'; + field: string; + by: string; + }; + sort?: { field: string; direction: 'asc' | 'desc' }; + limit?: number; +} +``` + +詳細は [@liqueur/protocol](../../packages/protocol) を参照。 + +--- + +## ロードマップ + +- [x] Phase 1: コアプロトコル & React コンポーネント +- [x] Phase 2: AI プロバイダー統合 +- [x] Phase 3: サンプルアプリ（家計簿） +- [ ] Phase 4: コンポーネント追加（カレンダー、マップ等） +- [ ] Phase 5: リアルタイム協調編集 +- [ ] Phase 6: プラグインシステム + +--- + +## 開発 + +```bash +pnpm install +pnpm build +pnpm test +``` + +詳細は [CONTRIBUTING.md](../../CONTRIBUTING.md) を参照。 + +--- + +## ライセンス + +[MIT](../../LICENSE) + +--- + +
+ +**Liquid Protocol** + +ユーザーが設定と格闘する時代を終わらせる + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.ru.md b/docs/readmeLangs/README.ru.md new file mode 100644 index 0000000..a03a42a --- /dev/null +++ b/docs/readmeLangs/README.ru.md @@ -0,0 +1,365 @@ +
+ +# Liquid Protocol + +**Управляйте дашбордами с помощью естественного языка.** + +Открытый протокол для генерации UI с помощью ИИ + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | Русский | [Українська](./README.uk.md) | [فارسی](./README.fa.md) | [العربية](./README.ar.md) + +
+ +--- + +## Суть + +**«Исключи транспортные расходы и покажи ежемесячные траты в виде столбчатой диаграммы»** + +Просто скажите это, и ваш дашборд автоматически перенастроится. + +
+ +| До | После | +|----|-------| +| ![Исходный дашборд](../images/dashboard-initial.png) | ![После обновления ИИ](../images/dashboard-after-ai.png) | +| Дашборд по умолчанию | После команды «Исключи транспорт» | + +
+ +--- + +## Быстрый старт (30 секунд) + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +Откройте [http://localhost:3000](http://localhost:3000) и начните общение. + +--- + +## Содержание + +- [Почему Liquid Protocol?](#почему-liquid-protocol) +- [Сравнение с Claude Artifacts / Gemini Canvas](#сравнение-с-claude-artifacts--gemini-canvas) +- [Варианты использования](#варианты-использования) +- [Как это работает](#как-это-работает) +- [Установка](#установка) +- [Настройка для разработчиков](#настройка-для-разработчиков) +- [Безопасность](#безопасность) +- [Спецификация схемы](#спецификация-схемы) +- [Дорожная карта](#дорожная-карта) + +--- + +## Почему Liquid Protocol? + +### Дилемма кастомизации + +Возьмём приложение для учёта расходов. Какое бы приложение вы ни использовали, у вас всегда будут такие запросы: + +> - «Исключи транспортные расходы — компания их компенсирует» +> - «Покупки по семейной карте — отдельно, их мне возмещают» +> - «Отметь все траты во время поездки как "путешествие"» +> - «Я не люблю красный — сделай синим и чёрным» + +**Текущие решения:** + +| Подход | Пример | Проблема | +|:-------|:-------|:---------| +| Сделать всё самому | Notion, Таблицы | Кастомизация становится целью. Теряется фокус | +| Добавить больше настроек | Традиционные приложения | Экраны настроек усложняются. «Слишком много свободы» | + +### Решение Liquid + +**Просто скажите, что вам нужно.** + +``` +Пользователь: «Исключи транспортные расходы» + ↓ +ИИ перегенерирует структуру дашборда + ↓ +Фильтры, графики и макеты обновляются автоматически +``` + +Больше не нужно искать нужные настройки. + +--- + +## Сравнение с Claude Artifacts / Gemini Canvas + +Вы использовали [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) или [Gemini Canvas](https://gemini.google/overview/canvas/)? + +Это замечательные функции, позволяющие генерировать дашборды и код через разговор с ИИ. + +**Liquid Protocol привносит этот опыт в ВАШЕ приложение.** + +| Функция | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|---------|:---------------:|:-------------:|:-------------------:| +| Генерация UI с помощью ИИ | ✅ | ✅ | ✅ | +| Встраивание в своё приложение | ❌ | ❌ | **✅** | +| Подключение своей БД | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| Риск выполнения кода | ⚠️ Песочница | ⚠️ Песочница | **✅ Нет** | +| Открытый исходный код | ❌ | ❌ | **✅ MIT** | +| Выбор ИИ-провайдера | Только Claude | Только Gemini | **Любой** | + +### Итог + +``` +Claude Artifacts / Gemini Canvas + → Потрясающе. Но только в ИХ приложениях. + +Liquid Protocol + → Тот же опыт в ВАШЕМ приложении. + Ваша база данных, ваши пользователи. +``` + +--- + +## Варианты использования + +Мы демонстрируем на примере бюджетного приложения, но эта технология применима к любому приложению: + +| Приложение | Традиционная проблема | Решение Liquid | +|:-----------|:---------------------|:---------------| +| **Slack / Discord** | Сложные настройки уведомлений | «Уведомляй только о важных разговорах» | +| **Биржевые приложения** | Фиксированные дашборды | «Покажи только техносектор круговой диаграммой» | +| **Twitter / SNS** | Непрозрачный алгоритм | «Скрой политический контент» | +| **Управление проектами** | Ад настроек Jira | «Покажи только мои задачи на этой неделе» | + +**Эта технология станет стандартом программного обеспечения.** + +--- + +## Как это работает + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Пользователь: «Исключи транспорт, покажи столбчатую» │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ ИИ (Claude / GPT / Gemini / DeepSeek / GLM) │ +│ │ +│ ⚠️ Выводит ТОЛЬКО JSON-схему. Не генерирует JS/SQL │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/protocol │ +│ │ +│ ✅ Валидация схемы: неизвестные поля сразу отклоняются │ +│ ✅ Двойная валидация TypeScript + Rust │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/db-adapter │ +│ │ +│ 🔒 Row-Level Security │ +│ 🔒 Защита от SQL-инъекций │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/react │ +│ │ +│ 📊 Автоматический рендеринг графиков, таблиц и макетов │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Установка + +### По назначению + +```bash +# Только определения схемы +npm install @liqueur/protocol + +# Добавить React UI +npm install @liqueur/protocol @liqueur/react + +# Полный стек (ИИ + БД) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +### Пакеты + +| Пакет | Назначение | +|:------|:-----------| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Типы схемы и валидация | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI-компоненты | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | Интеграция ИИ-провайдеров | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Выполнение Prisma-запросов | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Сохранение схем | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | CLI для создания проекта | + +--- + +## Настройка для разработчиков + +### Вариант 1: Быстрый старт с CLI + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# Настройте ИИ-провайдера +cp .env.example .env +# Отредактируйте .env, добавив API-ключ + +npm run dev +``` + +### Вариант 2: Добавление в существующий проект + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### Переменные окружения + +При использовании `@liqueur/ai-provider` настройте переменные окружения для выбранного ИИ-провайдера: + +```bash +# .env или .env.local + +# Выберите провайдера: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# Модели: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# Модели: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# Модели: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# Модели: deepseek-chat, deepseek-coder + +# ─── GLM (Zhipu AI) ─────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# Модели: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### Базовое использование + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// Создание провайдера из переменных окружения +const provider = ProviderFactory.createFromEnv(); + +// Генерация схемы из естественного языка +const schema = await provider.generateSchema( + "Покажи ежемесячные расходы столбчатой диаграммой", + databaseMetadata +); + +// Рендеринг дашборда + +``` + +### Пример: Next.js API Route + +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +### Примеры приложений + +| Пример | Описание | Запуск | +|:-------|:---------|:-------| +| [Учёт расходов](../../examples/household-budget) | Полнофункциональное с ИИ-чатом | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | Простая тестовая среда | `cd examples/playground && pnpm dev` | + +### Запуск из исходного кода + +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # Настройте API-ключи +pnpm dev +``` + +--- + +## Безопасность + +### Почему мы не даём ИИ писать JavaScript? + +| Подход | Риск | +|:-------|:-----| +| ИИ генерирует JS/SQL | XSS, SQL-инъекции, выполнение произвольного кода | +| **Liquid: только JSON** | Нет исполняемого кода. Неизвестные поля отклоняются | + +### Три уровня защиты + +1. **Ограничение вывода ИИ** — Только JSON-схема. Без генерации кода +2. **Валидация схемы** — Неизвестные поля немедленно отклоняются (Fail Fast) +3. **Row-Level Security** — Пользователи могут получить доступ только к своим данным + +--- + +## Дорожная карта + +- [x] Фаза 1: Основной протокол и React-компоненты +- [x] Фаза 2: Интеграция ИИ-провайдеров +- [x] Фаза 3: Пример приложения (бюджет) +- [ ] Фаза 4: Дополнительные компоненты (календарь, карта и т.д.) +- [ ] Фаза 5: Совместное редактирование в реальном времени +- [ ] Фаза 6: Система плагинов + +--- + +## Лицензия + +[MIT](../../LICENSE) + +--- + +
+ +**Liquid Protocol** + +Положим конец эпохе борьбы пользователей с настройками + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.uk.md b/docs/readmeLangs/README.uk.md new file mode 100644 index 0000000..14403a3 --- /dev/null +++ b/docs/readmeLangs/README.uk.md @@ -0,0 +1,365 @@ +
+ +# Liquid Protocol + +**Керуйте дашбордами за допомогою природної мови.** + +Відкритий протокол для генерації UI за допомогою ШІ + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | [繁體中文](./README.zh-TW.md) | [Русский](./README.ru.md) | Українська | [فارسی](./README.fa.md) | [العربية](./README.ar.md) + +
+ +--- + +## Суть + +**«Виключи транспортні витрати і покажи щомісячні витрати у вигляді стовпчастої діаграми»** + +Просто скажіть це, і ваш дашборд автоматично переналаштується. + +
+ +| До | Після | +|----|-------| +| ![Початковий дашборд](../images/dashboard-initial.png) | ![Після оновлення ШІ](../images/dashboard-after-ai.png) | +| Дашборд за замовчуванням | Після команди «Виключи транспорт» | + +
+ +--- + +## Швидкий старт (30 секунд) + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +Відкрийте [http://localhost:3000](http://localhost:3000) і почніть спілкування. + +--- + +## Зміст + +- [Чому Liquid Protocol?](#чому-liquid-protocol) +- [Порівняння з Claude Artifacts / Gemini Canvas](#порівняння-з-claude-artifacts--gemini-canvas) +- [Варіанти використання](#варіанти-використання) +- [Як це працює](#як-це-працює) +- [Встановлення](#встановлення) +- [Налаштування для розробників](#налаштування-для-розробників) +- [Безпека](#безпека) +- [Специфікація схеми](#специфікація-схеми) +- [Дорожня карта](#дорожня-карта) + +--- + +## Чому Liquid Protocol? + +### Дилема кастомізації + +Візьмемо додаток для обліку витрат. Який би додаток ви не використовували, у вас завжди будуть такі запити: + +> - «Виключи транспортні витрати — компанія їх компенсує» +> - «Покупки по сімейній картці — окремо, їх мені відшкодовують» +> - «Позначи всі витрати під час подорожі як "подорож"» +> - «Я не люблю червоний — зроби синім і чорним» + +**Поточні рішення:** + +| Підхід | Приклад | Проблема | +|:-------|:--------|:---------| +| Зробити все самому | Notion, Таблиці | Кастомізація стає метою. Втрачається фокус | +| Додати більше налаштувань | Традиційні додатки | Екрани налаштувань ускладнюються. «Занадто багато свободи» | + +### Рішення Liquid + +**Просто скажіть, що вам потрібно.** + +``` +Користувач: «Виключи транспортні витрати» + ↓ +ШІ перегенерує структуру дашборда + ↓ +Фільтри, графіки та макети оновлюються автоматично +``` + +Більше не потрібно шукати потрібні налаштування. + +--- + +## Порівняння з Claude Artifacts / Gemini Canvas + +Ви використовували [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) або [Gemini Canvas](https://gemini.google/overview/canvas/)? + +Це чудові функції, що дозволяють генерувати дашборди та код через розмову з ШІ. + +**Liquid Protocol привносить цей досвід у ВАШ додаток.** + +| Функція | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|---------|:---------------:|:-------------:|:-------------------:| +| Генерація UI за допомогою ШІ | ✅ | ✅ | ✅ | +| Вбудовування у свій додаток | ❌ | ❌ | **✅** | +| Підключення своєї БД | ❌ | ❌ | **✅** | +| Row-Level Security | ❌ | ❌ | **✅** | +| Ризик виконання коду | ⚠️ Пісочниця | ⚠️ Пісочниця | **✅ Немає** | +| Відкритий вихідний код | ❌ | ❌ | **✅ MIT** | +| Вибір ШІ-провайдера | Лише Claude | Лише Gemini | **Будь-який** | + +### Підсумок + +``` +Claude Artifacts / Gemini Canvas + → Вражаюче. Але лише в ЇХ додатках. + +Liquid Protocol + → Той самий досвід у ВАШОМУ додатку. + Ваша база даних, ваші користувачі. +``` + +--- + +## Варіанти використання + +Ми демонструємо на прикладі бюджетного додатку, але ця технологія застосовна до будь-якого додатку: + +| Додаток | Традиційна проблема | Рішення Liquid | +|:--------|:-------------------|:---------------| +| **Slack / Discord** | Складні налаштування сповіщень | «Сповіщай лише про важливі розмови» | +| **Біржові додатки** | Фіксовані дашборди | «Покажи лише техносектор круговою діаграмою» | +| **Twitter / SNS** | Непрозорий алгоритм | «Сховай політичний контент» | +| **Управління проєктами** | Пекло налаштувань Jira | «Покажи лише мої завдання на цьому тижні» | + +**Ця технологія стане стандартом програмного забезпечення.** + +--- + +## Як це працює + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Користувач: «Виключи транспорт, покажи стовпчасту» │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ ШІ (Claude / GPT / Gemini / DeepSeek / GLM) │ +│ │ +│ ⚠️ Виводить ЛИШЕ JSON-схему. Не генерує JS/SQL │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/protocol │ +│ │ +│ ✅ Валідація схеми: невідомі поля одразу відхиляються │ +│ ✅ Подвійна валідація TypeScript + Rust │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/db-adapter │ +│ │ +│ 🔒 Row-Level Security │ +│ 🔒 Захист від SQL-ін'єкцій │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/react │ +│ │ +│ 📊 Автоматичний рендеринг графіків, таблиць та макетів │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## Встановлення + +### За призначенням + +```bash +# Лише визначення схеми +npm install @liqueur/protocol + +# Додати React UI +npm install @liqueur/protocol @liqueur/react + +# Повний стек (ШІ + БД) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +### Пакети + +| Пакет | Призначення | +|:------|:------------| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Типи схеми та валідація | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI-компоненти | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | Інтеграція ШІ-провайдерів | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Виконання Prisma-запитів | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Збереження схем | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | CLI для створення проєкту | + +--- + +## Налаштування для розробників + +### Варіант 1: Швидкий старт з CLI + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# Налаштуйте ШІ-провайдера +cp .env.example .env +# Відредагуйте .env, додавши API-ключ + +npm run dev +``` + +### Варіант 2: Додавання до існуючого проєкту + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### Змінні оточення + +При використанні `@liqueur/ai-provider` налаштуйте змінні оточення для обраного ШІ-провайдера: + +```bash +# .env або .env.local + +# Оберіть провайдера: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# Моделі: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# Моделі: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# Моделі: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# Моделі: deepseek-chat, deepseek-coder + +# ─── GLM (Zhipu AI) ─────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# Моделі: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### Базове використання + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// Створення провайдера зі змінних оточення +const provider = ProviderFactory.createFromEnv(); + +// Генерація схеми з природної мови +const schema = await provider.generateSchema( + "Покажи щомісячні витрати стовпчастою діаграмою", + databaseMetadata +); + +// Рендеринг дашборда + +``` + +### Приклад: Next.js API Route + +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +### Приклади додатків + +| Приклад | Опис | Запуск | +|:--------|:-----|:-------| +| [Облік витрат](../../examples/household-budget) | Повнофункціональний з ШІ-чатом | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | Просте тестове середовище | `cd examples/playground && pnpm dev` | + +### Запуск з вихідного коду + +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # Налаштуйте API-ключі +pnpm dev +``` + +--- + +## Безпека + +### Чому ми не даємо ШІ писати JavaScript? + +| Підхід | Ризик | +|:-------|:------| +| ШІ генерує JS/SQL | XSS, SQL-ін'єкції, виконання довільного коду | +| **Liquid: лише JSON** | Немає виконуваного коду. Невідомі поля відхиляються | + +### Три рівні захисту + +1. **Обмеження виводу ШІ** — Лише JSON-схема. Без генерації коду +2. **Валідація схеми** — Невідомі поля негайно відхиляються (Fail Fast) +3. **Row-Level Security** — Користувачі можуть отримати доступ лише до своїх даних + +--- + +## Дорожня карта + +- [x] Фаза 1: Основний протокол та React-компоненти +- [x] Фаза 2: Інтеграція ШІ-провайдерів +- [x] Фаза 3: Приклад додатку (бюджет) +- [ ] Фаза 4: Додаткові компоненти (календар, карта тощо) +- [ ] Фаза 5: Спільне редагування в реальному часі +- [ ] Фаза 6: Система плагінів + +--- + +## Ліцензія + +[MIT](../../LICENSE) + +--- + +
+ +**Liquid Protocol** + +Покладемо край епосі боротьби користувачів з налаштуваннями + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.zh-CN.md b/docs/readmeLangs/README.zh-CN.md new file mode 100644 index 0000000..0e44a94 --- /dev/null +++ b/docs/readmeLangs/README.zh-CN.md @@ -0,0 +1,329 @@ +
+ +# Liquid Protocol + +**用自然语言自由定制仪表板。** + +AI驱动UI生成的开源协议 + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | 简体中文 | [繁體中文](./README.zh-TW.md) | [Русский](./README.ru.md) | [Українська](./README.uk.md) | [فارسی](./README.fa.md) | [العربية](./README.ar.md) + +
+ +--- + +## 简而言之 + +**"排除交通费，用柱状图显示每月支出"** + +只需说这句话，仪表板就会自动重新配置。 + +
+ +| 之前 | 之后 | +|------|------| +| ![初始仪表板](../images/dashboard-initial.png) | ![AI更新后](../images/dashboard-after-ai.png) | +| 默认仪表板 | 说"排除交通费"之后 | + +
+ +--- + +## 30秒快速开始 + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +打开 [http://localhost:3000](http://localhost:3000)，开始对话即可。 + +--- + +## 目录 + +- [为什么选择 Liquid Protocol？](#为什么选择-liquid-protocol) +- [与 Claude Artifacts / Gemini Canvas 的区别](#与-claude-artifacts--gemini-canvas-的区别) +- [应用场景](#应用场景) +- [工作原理](#工作原理) +- [安装](#安装) +- [开发者设置](#开发者设置) +- [安全设计](#安全设计) +- [Schema 规范](#schema-规范) +- [路线图](#路线图) + +--- + +## 为什么选择 Liquid Protocol？ + +### 定制化的两难困境 + +以记账应用为例。无论使用哪个应用，你总会有这样的需求： + +> - "排除交通费 - 公司会报销" +> - "家庭卡消费要分开 - 会得到退款" +> - "给旅行期间的消费加上'旅行'标签" +> - "我不喜欢红色 - 换成蓝色和黑色" + +**现有解决方案：** + +| 方式 | 示例 | 问题 | +|:----|:-----|:-----| +| 自己全部构建 | Notion, 电子表格 | 定制成为目的，偏离正轨 | +| 增加设置项 | 传统应用 | 设置界面变得复杂。"太自由反而不自由" | + +### Liquid 的解决方案 + +**只需说出你想要的。** + +``` +用户: "排除交通费" + ↓ +AI 重新生成仪表板结构 + ↓ +过滤器、图表、布局自动更新 +``` + +不再需要在设置界面中四处寻找。 + +--- + +## 与 Claude Artifacts / Gemini Canvas 的区别 + +你用过 [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) 或 [Gemini Canvas](https://gemini.google/overview/canvas/) 吗？ + +它们是很棒的功能，可以通过AI对话生成仪表板和代码。 + +**Liquid Protocol 将这种体验带到你自己的应用中。** + +| 功能 | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|------|:---------------:|:-------------:|:-------------------:| +| AI驱动的UI生成 | ✅ | ✅ | ✅ | +| 嵌入自己的应用 | ❌ | ❌ | **✅** | +| 连接自己的数据库 | ❌ | ❌ | **✅** | +| 行级安全 | ❌ | ❌ | **✅** | +| 代码执行风险 | ⚠️ 沙箱 | ⚠️ 沙箱 | **✅ 无** | +| 开源 | ❌ | ❌ | **✅ MIT** | +| AI提供商选择 | 仅Claude | 仅Gemini | **任意** | + +### 总结 + +``` +Claude Artifacts / Gemini Canvas + → 很棒。但只在他们的应用中。 + +Liquid Protocol + → 在你自己的应用中实现同样的体验。 + 你的数据库，你的用户。 +``` + +--- + +## 应用场景 + +我们用记账应用来演示，但这项技术适用于任何应用： + +| 应用 | 传统问题 | Liquid 解决方案 | +|:----|:--------|:---------------| +| **Slack / Discord** | 通知设置复杂 | "只通知重要对话" | +| **股票交易** | 仪表板固定 | "只用饼图显示科技股" | +| **Twitter / SNS** | 算法不透明 | "隐藏政治内容" | +| **项目管理** | Jira 设置地狱 | "只显示本周我的任务" | + +**这项技术将成为软件标准。** + +--- + +## 工作原理 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户: "排除交通费，用柱状图显示" │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ AI (Claude / GPT / Gemini / DeepSeek / GLM) │ +│ │ +│ ⚠️ 仅输出 JSON schema。不生成 JS/SQL │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/protocol │ +│ │ +│ ✅ Schema 验证: 未知字段立即拒绝 │ +│ ✅ TypeScript + Rust 双重验证 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/db-adapter │ +│ │ +│ 🔒 行级安全 │ +│ 🔒 SQL注入防护 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/react │ +│ │ +│ 📊 自动渲染图表、表格和布局 │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 安装 + +### 按用途 + +```bash +# 仅 Schema 定义 +npm install @liqueur/protocol + +# 添加 React UI +npm install @liqueur/protocol @liqueur/react + +# 全栈 (AI + 数据库) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +### 包列表 + +| 包 | 用途 | +|:--|:-----| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Schema 类型 & 验证 | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI 组件 | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI 提供商集成 | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma 查询执行 | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Schema 持久化 | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | 项目脚手架 CLI | + +--- + +## 开发者设置 + +### 方式1: CLI 快速开始 + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# 配置 AI 提供商 +cp .env.example .env +# 编辑 .env 添加 API key + +npm run dev +``` + +### 方式2: 添加到现有项目 + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### 环境变量 + +使用 `@liqueur/ai-provider` 时，为选择的 AI 提供商配置环境变量： + +```bash +# .env 或 .env.local + +# 选择提供商: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# 模型: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# 模型: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# 模型: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# 模型: deepseek-chat, deepseek-coder + +# ─── GLM (智谱 AI) ──────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# 模型: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### 基本用法 + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// 从环境变量创建提供商 +const provider = ProviderFactory.createFromEnv(); + +// 从自然语言生成 schema +const schema = await provider.generateSchema( + "用柱状图显示每月支出", + databaseMetadata +); + +// 渲染仪表板 + +``` + +--- + +## 安全设计 + +### 为什么不让 AI 写 JavaScript？ + +| 方式 | 风险 | +|:----|:-----| +| AI 生成 JS/SQL | XSS、SQL注入、任意代码执行 | +| **Liquid: 仅 JSON** | 无可执行代码。未知字段被拒绝 | + +### 三层防御 + +1. **AI 输出限制** — 仅 JSON schema。不生成代码 +2. **Schema 验证** — 未知字段立即拒绝（Fail Fast） +3. **行级安全** — 用户只能访问自己的数据 + +--- + +## 路线图 + +- [x] Phase 1: 核心协议 & React 组件 +- [x] Phase 2: AI 提供商集成 +- [x] Phase 3: 示例应用（记账） +- [ ] Phase 4: 添加组件（日历、地图等） +- [ ] Phase 5: 实时协作编辑 +- [ ] Phase 6: 插件系统 + +--- + +## 许可证 + +[MIT](../../LICENSE) + +--- + +
+ +**Liquid Protocol** + +终结用户与设置搏斗的时代 + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/docs/readmeLangs/README.zh-TW.md b/docs/readmeLangs/README.zh-TW.md new file mode 100644 index 0000000..cfb3360 --- /dev/null +++ b/docs/readmeLangs/README.zh-TW.md @@ -0,0 +1,365 @@ +
+ +# Liquid Protocol + +**用自然語言自由定製儀表板。** + +AI驅動UI生成的開源協議 + +[![npm](https://img.shields.io/npm/v/@liqueur/protocol?style=flat-square&color=blue)](https://www.npmjs.com/package/@liqueur/protocol) +[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](../../LICENSE) + +[English](../../README.md) | [日本語](./README.ja.md) | [简体中文](./README.zh-CN.md) | 繁體中文 | [Русский](./README.ru.md) | [Українська](./README.uk.md) | [فارسی](./README.fa.md) | [العربية](./README.ar.md) + +
+ +--- + +## 簡而言之 + +**「排除交通費，用長條圖顯示每月支出」** + +只需說這句話，儀表板就會自動重新配置。 + +
+ +| 之前 | 之後 | +|------|------| +| ![初始儀表板](../images/dashboard-initial.png) | ![AI更新後](../images/dashboard-after-ai.png) | +| 預設儀表板 | 說「排除交通費」之後 | + +
+ +--- + +## 30秒快速開始 + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard +npm run dev +``` + +開啟 [http://localhost:3000](http://localhost:3000)，開始對話即可。 + +--- + +## 目錄 + +- [為什麼選擇 Liquid Protocol？](#為什麼選擇-liquid-protocol) +- [與 Claude Artifacts / Gemini Canvas 的區別](#與-claude-artifacts--gemini-canvas-的區別) +- [應用場景](#應用場景) +- [工作原理](#工作原理) +- [安裝](#安裝) +- [開發者設定](#開發者設定) +- [安全設計](#安全設計) +- [Schema 規範](#schema-規範) +- [路線圖](#路線圖) + +--- + +## 為什麼選擇 Liquid Protocol？ + +### 定製化的兩難困境 + +以記帳應用為例。無論使用哪個應用，你總會有這樣的需求： + +> - 「排除交通費 - 公司會報銷」 +> - 「家庭卡消費要分開 - 會得到退款」 +> - 「給旅行期間的消費加上『旅行』標籤」 +> - 「我不喜歡紅色 - 換成藍色和黑色」 + +**現有解決方案：** + +| 方式 | 範例 | 問題 | +|:----|:-----|:-----| +| 自己全部建構 | Notion, 電子表格 | 定製成為目的，偏離正軌 | +| 增加設定項 | 傳統應用 | 設定介面變得複雜。「太自由反而不自由」 | + +### Liquid 的解決方案 + +**只需說出你想要的。** + +``` +使用者: 「排除交通費」 + ↓ +AI 重新生成儀表板結構 + ↓ +篩選器、圖表、佈局自動更新 +``` + +不再需要在設定介面中四處尋找。 + +--- + +## 與 Claude Artifacts / Gemini Canvas 的區別 + +你用過 [Claude Artifacts](https://support.anthropic.com/en/articles/9487310-what-are-artifacts-and-how-do-i-use-them) 或 [Gemini Canvas](https://gemini.google/overview/canvas/) 嗎？ + +它們是很棒的功能，可以透過AI對話生成儀表板和程式碼。 + +**Liquid Protocol 將這種體驗帶到你自己的應用中。** + +| 功能 | Claude Artifacts | Gemini Canvas | **Liquid Protocol** | +|------|:---------------:|:-------------:|:-------------------:| +| AI驅動的UI生成 | ✅ | ✅ | ✅ | +| 嵌入自己的應用 | ❌ | ❌ | **✅** | +| 連接自己的資料庫 | ❌ | ❌ | **✅** | +| 行級安全 | ❌ | ❌ | **✅** | +| 程式碼執行風險 | ⚠️ 沙箱 | ⚠️ 沙箱 | **✅ 無** | +| 開源 | ❌ | ❌ | **✅ MIT** | +| AI提供商選擇 | 僅Claude | 僅Gemini | **任意** | + +### 總結 + +``` +Claude Artifacts / Gemini Canvas + → 很棒。但只在他們的應用中。 + +Liquid Protocol + → 在你自己的應用中實現同樣的體驗。 + 你的資料庫，你的使用者。 +``` + +--- + +## 應用場景 + +我們用記帳應用來演示，但這項技術適用於任何應用： + +| 應用 | 傳統問題 | Liquid 解決方案 | +|:----|:--------|:---------------| +| **Slack / Discord** | 通知設定複雜 | 「只通知重要對話」 | +| **股票交易** | 儀表板固定 | 「只用圓餅圖顯示科技股」 | +| **Twitter / SNS** | 演算法不透明 | 「隱藏政治內容」 | +| **專案管理** | Jira 設定地獄 | 「只顯示本週我的任務」 | + +**這項技術將成為軟體標準。** + +--- + +## 工作原理 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 使用者: 「排除交通費，用長條圖顯示」 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ AI (Claude / GPT / Gemini / DeepSeek / GLM) │ +│ │ +│ ⚠️ 僅輸出 JSON schema。不生成 JS/SQL │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/protocol │ +│ │ +│ ✅ Schema 驗證: 未知欄位立即拒絕 │ +│ ✅ TypeScript + Rust 雙重驗證 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/db-adapter │ +│ │ +│ 🔒 行級安全 │ +│ 🔒 SQL注入防護 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ @liqueur/react │ +│ │ +│ 📊 自動渲染圖表、表格和佈局 │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 安裝 + +### 按用途 + +```bash +# 僅 Schema 定義 +npm install @liqueur/protocol + +# 新增 React UI +npm install @liqueur/protocol @liqueur/react + +# 全端 (AI + 資料庫) +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider @liqueur/db-adapter +``` + +### 套件列表 + +| 套件 | 用途 | +|:----|:-----| +| [@liqueur/protocol](https://www.npmjs.com/package/@liqueur/protocol) | Schema 類型 & 驗證 | +| [@liqueur/react](https://www.npmjs.com/package/@liqueur/react) | UI 元件 | +| [@liqueur/ai-provider](https://www.npmjs.com/package/@liqueur/ai-provider) | AI 提供商整合 | +| [@liqueur/db-adapter](https://www.npmjs.com/package/@liqueur/db-adapter) | Prisma 查詢執行 | +| [@liqueur/artifact-store](https://www.npmjs.com/package/@liqueur/artifact-store) | Schema 持久化 | +| [create-next-liqueur-app](https://www.npmjs.com/package/create-next-liqueur-app) | 專案腳手架 CLI | + +--- + +## 開發者設定 + +### 方式1: CLI 快速開始 + +```bash +npx create-next-liqueur-app my-dashboard +cd my-dashboard + +# 設定 AI 提供商 +cp .env.example .env +# 編輯 .env 新增 API key + +npm run dev +``` + +### 方式2: 新增到現有專案 + +```bash +npm install @liqueur/protocol @liqueur/react @liqueur/ai-provider +``` + +### 環境變數 + +使用 `@liqueur/ai-provider` 時，為選擇的 AI 提供商設定環境變數： + +```bash +# .env 或 .env.local + +# 選擇提供商: anthropic, openai, gemini, deepseek, glm, local +AI_PROVIDER=anthropic + +# ─── Anthropic (Claude) ─────────────────────────────── +ANTHROPIC_API_KEY=sk-ant-your-key +ANTHROPIC_MODEL=claude-3-5-haiku-20241022 +# 模型: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 + +# ─── OpenAI (GPT) ───────────────────────────────────── +OPENAI_API_KEY=sk-your-key +OPENAI_MODEL=gpt-4o-mini +# 模型: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo + +# ─── Google Gemini ──────────────────────────────────── +GOOGLE_API_KEY=your-key +GEMINI_MODEL=gemini-1.5-flash +# 模型: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash + +# ─── DeepSeek ───────────────────────────────────────── +DEEPSEEK_API_KEY=sk-your-key +DEEPSEEK_MODEL=deepseek-chat +# 模型: deepseek-chat, deepseek-coder + +# ─── GLM (智譜 AI) ──────────────────────────────────── +GLM_API_KEY=your-key +GLM_MODEL=glm-4 +# 模型: glm-4, glm-4-flash, glm-3-turbo + +# ─── Local LLM (Ollama, LM Studio) ──────────────────── +LOCAL_LLM_BASE_URL=http://localhost:1234/v1 +LOCAL_LLM_MODEL=llama3 +``` + +### 基本用法 + +```typescript +import { ProviderFactory } from '@liqueur/ai-provider'; +import { LiquidRenderer } from '@liqueur/react'; + +// 從環境變數建立 Provider +const provider = ProviderFactory.createFromEnv(); + +// 從自然語言生成 Schema +const schema = await provider.generateSchema( + "用長條圖顯示每月支出", + databaseMetadata +); + +// 渲染儀表板 + +``` + +### 範例：Next.js API Route + +```typescript +// app/api/generate/route.ts +import { NextRequest, NextResponse } from 'next/server'; +import { ProviderFactory } from '@liqueur/ai-provider'; + +export async function POST(request: NextRequest) { + const { prompt } = await request.json(); + + const provider = ProviderFactory.createFromEnv(); + const schema = await provider.generateSchema(prompt, metadata); + + return NextResponse.json({ schema }); +} +``` + +### 範例應用 + +| 範例 | 說明 | 執行 | +|:----|:-----|:----| +| [家計簿應用](../../examples/household-budget) | 具備 AI 聊天的完整功能 | `cd examples/household-budget && pnpm dev` | +| [Playground](../../examples/playground) | 簡單測試環境 | `cd examples/playground && pnpm dev` | + +### 從原始碼執行 + +```bash +git clone https://github.com/clearclown/liqueur.git +cd liqueur +pnpm install && pnpm build + +cd examples/household-budget +cp .env.example .env # 設定 API 金鑰 +pnpm dev +``` + +--- + +## 安全設計 + +### 為什麼不讓 AI 寫 JavaScript？ + +| 方式 | 風險 | +|:----|:-----| +| AI 生成 JS/SQL | XSS、SQL注入、任意程式碼執行 | +| **Liquid: 僅 JSON** | 無可執行程式碼。未知欄位被拒絕 | + +### 三層防禦 + +1. **AI 輸出限制** — 僅 JSON schema。不生成程式碼 +2. **Schema 驗證** — 未知欄位立即拒絕（Fail Fast） +3. **行級安全** — 使用者只能存取自己的資料 + +--- + +## 路線圖 + +- [x] Phase 1: 核心協議 & React 元件 +- [x] Phase 2: AI 提供商整合 +- [x] Phase 3: 範例應用（記帳） +- [ ] Phase 4: 新增元件（日曆、地圖等） +- [ ] Phase 5: 即時協作編輯 +- [ ] Phase 6: 外掛系統 + +--- + +## 授權條款 + +[MIT](../../LICENSE) + +--- + +
+ +**Liquid Protocol** + +終結使用者與設定搏鬥的時代 + +[GitHub](https://github.com/clearclown/liqueur) · [npm](https://www.npmjs.com/package/@liqueur/protocol) + +
diff --git a/packages/db-adapter/src/executor/types.ts b/packages/db-adapter/src/executor/types.ts index 76d6718..cced852 100644 --- a/packages/db-adapter/src/executor/types.ts +++ b/packages/db-adapter/src/executor/types.ts @@ -4,7 +4,8 @@ * Types for executing DataSource queries against Prisma */ -import type { DataSource, FilterOperator } from "@liqueur/protocol"; +// Note: DataSource and FilterOperator are used through the protocol package +// This file only contains executor-specific type definitions /** * Configuration for DataSource execution diff --git a/packages/db-adapter/src/types/index.ts b/packages/db-adapter/src/types/index.ts index 056ab61..816fb94 100644 --- a/packages/db-adapter/src/types/index.ts +++ b/packages/db-adapter/src/types/index.ts @@ -2,7 +2,7 @@ * Database Adapter Types */ -import type { DatabaseMetadata, Table, Column } from "@liqueur/protocol"; +import type { DatabaseMetadata, Table } from "@liqueur/protocol"; /** * Database introspector interface diff --git a/packages/db-adapter/tsconfig.json b/packages/db-adapter/tsconfig.json index 9f4d050..106c31d 100644 --- a/packages/db-adapter/tsconfig.json +++ b/packages/db-adapter/tsconfig.json @@ -1,5 +1,5 @@ { - "extends": "../../tsconfig.json", + "extends": "../../tsconfig.base.json", "compilerOptions": { "outDir": "./dist", "rootDir": "./src",