弗莱
- 作者仓库星标 0
- 作者仓库 flai
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @Zacherieunexceptional123 · 未声明许可证
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · OpenAI / Anthropic
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# FlAI -- AI Chat Components for Flutter
FlAI is a shadcn/ui-style component library for Flutter that gives you production-ready AI chat UI as source code you own. Components are distributed via a Mason-powered CLI -- you install exactly what you need, and the code lives in your project.
Docs: https://getflai.dev
## When to Use This Skill
- User wants to add AI chat UI to a Flutter app
- User asks about FlAI components (message bubbles, input bars, streaming text, etc.)
- User needs help with FlAI theming (colors, typography, spacing, radius, icons)
- User wants to connect to OpenAI or Anthropic APIs
- User asks about building a chat screen, conversation list, or model selector
## Installation
### Prerequisites
- Flutter 3.22+ with Dart 3.4+
- An existing Flutter project
### Install the CLI
```bash
dart pub global activate flai_cli
```
### Initialize FlAI in Your Project
```bash
flai init
```
This runs the `flai_init` brick, generating the core foundation into your `lib/` directory:
- `core/theme/` -- FlaiTheme, FlaiColors, FlaiTypography, FlaiRadius, FlaiSpacing, FlaiIconData
- `core/models/` -- Message, Conversation, ChatEvent (sealed class), ChatRequest
- `providers/ai_provider.dart` -- Abstract AiProvider interface
- `flai.dart` -- Barrel export file
### Add Components
```bash
flai add chat_screen
flai add message_bubble
flai add input_bar
flai add openai_provider
```
You can add multiple components at once:
```bash
flai add chat_screen message_bubble input_bar streaming_text typing_indicator
```
## Available Components
### Chat Essentials
| Component | Command | Description |
|---|---|---|
| `chat_screen` | `flai add chat_screen` | Full chat screen with header, message list, and input bar. Depends on: message_bubble, input_bar, streaming_text, typing_indicator |
| `message_bubble` | `flai add message_bubble` | Message bubble with user/assistant styling, thinking blocks, tool call chips, citations, streaming cursor, and error retry |
| `input_bar` | `flai add input_bar` | Text input with send button, attachment support, Enter-to-send on desktop, multi-line growth |
| `streaming_text` | `flai add streaming_text` | Token-by-token text rendering with blinking cursor. Two modes: stream-driven or text-driven |
| `typing_indicator` | `flai add typing_indicator` | Animated three-dot bouncing indicator styled as an assistant bubble |
### AI Widgets
| Component | Command | Description |
|---|---|---|
| `tool_call_card` | `flai add tool_call_card` | Function/tool call display card with status and arguments |
| `code_block` | `flai add code_block` | Syntax-highlighted code display with copy-to-clipboard |
| `thinking_indicator` | `flai add thinking_indicator` | AI reasoning/thinking panel (collapsible) |
| `citation_card` | `flai add citation_card` | Source attribution card with title, URL, and snippet |
| `image_preview` | `flai add image_preview` | Image thumbnail with tap-to-zoom |
### Conversation Management
| Component | Command | Description |
|---|---|---|
| `conversation_list` | `flai add conversation_list` | Conversation history list with search and selection |
| `model_selector` | `flai add model_selector` | AI model picker dropdown |
| `token_usage` | `flai add token_usage` | Token count display (input/output/cache) |
### AI Providers
| Provider | Command | Description |
|---|---|---|
| `openai_provider` | `flai add openai_provider` | OpenAI Chat Completions API with streaming, tool use, and vision. Uses raw HTTP (package:http) |
| `anthropic_provider` | `flai add anthropic_provider` | Anthropic Messages API with streaming, tool use, extended thinking, and vision. Uses raw HTTP (package:http) |
## Quick Start -- Complete Chat App
Here is the minimal code to get a working AI chat screen:
### 1. Install and add components
```bash
dart pub global activate flai_cli
flai init
flai add chat_screen openai_provider
```
### 2. Set up the app
```dart
import 'package:flutter/material.dart';
import 'flai/flai.dart';
import 'flai/components/chat_screen/chat_screen.dart';
import 'flai/components/chat_screen/chat_screen_controller.dart';
import 'flai/providers/openai_provider.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return FlaiTheme(
data: FlaiThemeData.dark(),
child: MaterialApp(
title: 'AI Chat',
theme: ThemeData.dark(),
home: const ChatPage(),
),
);
}
}
class ChatPage extends StatefulWidget {
const ChatPage({super.key});
@override
State<ChatPage> createState() => _ChatPageState();
}
class _ChatPageState extends State<ChatPage> {
late final ChatScreenController _controller;
@override
void initState() {
super.initState();
_controller = ChatScreenController(
provider: OpenAiProvider(
apiKey: const String.fromEnvironment('OPENAI_API_KEY'),
model: 'gpt-4o',
),
systemPrompt: 'You are a helpful assistant.',
);
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: FlaiChatScreen(
controller: _controller,
title: 'AI Assistant',
subtitle: 'GPT-4o',
),
);
}
}
```
### 3. Run with your API key
```bash
flutter run --dart-define=OPENAI_API_KEY=sk-your-key-here
```
## Theming
FlAI uses an InheritedWidget-based theme system with semantic color tokens modeled after shadcn/ui.
### FlaiThemeData
`FlaiThemeData` composes five sub-systems:
| Field | Type | Description |
|---|---|---|
| `colors` | `FlaiColors` | Semantic color tokens (background, foreground, primary, muted, userBubble, etc.) |
| `icons` | `FlaiIconData` | Semantic icon set (20 icon fields). Defaults to `FlaiIconData.material()` |
| `typography` | `FlaiTypography` | Font families and size scale |
| `radius` | `FlaiRadius` | Border radius tokens |
| `spacing` | `FlaiSpacing` | Spacing tokens |
### Built-in Presets
| Preset | Factory | Icons | Description |
|---|---|---|---|
| Zinc Light | `FlaiThemeData.light()` | `FlaiIconData.material()` | Clean light theme with zinc neutrals |
| Zinc Dark | `FlaiThemeData.dark()` | `FlaiIconData.material()` | Dark theme with zinc neutrals |
| iOS | `FlaiThemeData.ios()` | `FlaiIconData.cupertino()` | Apple Messages-inspired blue bubbles, iOS system colors, larger radii, Cupertino icons |
| Premium | `FlaiThemeData.premium()` | `FlaiIconData.sharp()` | Linear-inspired dark theme with indigo accents, sharp Material icons |
### FlaiIconData
Semantic icon set with 20 fields. Components access icons via `FlaiTheme.of(context).icons` instead of hardcoding `Icons.*` or `CupertinoIcons.*`.
**Presets:**
- `FlaiIconData.material()` -- Material Design rounded icons (default for light/dark)
- `FlaiIconData.cupertino()` -- Apple SF Symbols style (used by ios() preset)
- `FlaiIconData.sharp()` -- Material Design sharp icons (used by premium() preset)
**Icon fields:** toolCall, thinking, citation, image, brokenImage, code, copy, check, close, send, attach, search, delete, add, expand, collapse, chat, model, refresh, error
```dart
// Override specific icons on a preset
final customTheme = FlaiThemeData.dark().copyWith(
icons: FlaiIconData.material().copyWith(
send: Icons.arrow_upward_rounded,
chat: Icons.forum_rounded,
),
);
```
### Applying a Theme
Wrap your app (or a subtree) with `FlaiTheme`:
```dart
FlaiTheme(
data: FlaiThemeData.dark(),
child: MaterialApp(
home: ChatPage(),
),
)
```
All FlAI widgets read their styling via `FlaiTheme.of(context)`.
### Custom Theme
Create a fully custom theme by constructing `FlaiThemeData` directly:
```dart
final myTheme = FlaiThemeData(
colors: FlaiColors(
background: Color(0xFF0F172A),
foreground: Color(0xFFF8FAFC),
card: Color(0xFF1E293B),
cardForeground: Color(0xFFF8FAFC),
popover: Color(0xFF1E293B),
popoverForeground: Color(0xFFF8FAFC),
primary: Color(0xFF3B82F6),
primaryForeground: Color(0xFFFFFFFF),
secondary: Color(0xFF334155),
secondaryForeground: Color(0xFFF8FAFC),
muted: Color(0xFF334155),
mutedForeground: Color(0xFF94A3B8),
accent: Color(0xFF3B82F6),
accentForeground: Color(0xFFFFFFFF),
destructive: Color(0xFFEF4444),
destructiveForeground: Color(0xFFFFFFFF),
border: Color(0xFF334155),
input: Color(0xFF334155),
ring: Color(0xFF3B82F6),
userBubble: Color(0xFF3B82F6),
userBubbleForeground: Color(0xFFFFFFFF),
assistantBubble: Color(0xFF1E293B),
assistantBubbleForeground: Color(0xFFF8FAFC),
),
icons: FlaiIconData.material(), // or .cupertino(), .sharp(), or custom
typography: FlaiTypography(
fontFamily: 'Inter',
monoFontFamily: 'Fira Code',
base: 15.0,
),
radius: FlaiRadius(sm: 6, md: 10, lg: 16, xl: 20, full: 9999),
spacing: FlaiSpacing(xs: 4, sm: 8, md: 16, lg: 24, xl: 32, xxl: 48),
);
```
### Modifying a Preset
Use `copyWith` to tweak an existing preset:
```dart
final customDark = FlaiThemeData.dark().copyWith(
colors: FlaiColors.dark().copyWith(
primary: Color(0xFF10B981), // emerald accent
userBubble: Color(0xFF10B981),
userBubbleForeground: Color(0xFFFFFFFF),
),
icons: FlaiIconData.cupertino(), // swap to Cupertino icons
typography: FlaiTypography(fontFamily: 'Inter'),
);
```
### Theme Token Reference
**Colors:** background, foreground, card, cardForeground, popover, popoverForeground, primary, primaryForeground, secondary, secondaryForeground, muted, mutedForeground, accent, accentForeground, destructive, destructiveForeground, border, input, ring, userBubble, userBubbleForeground, assistantBubble, assistantBubbleForeground
**Icons:** toolCall, thinking, citation, image, brokenImage, code, copy, check, close, send, attach, search, delete, add, expand, collapse, chat, model, refresh, error
**Typography:** fontFamily, monoFontFamily, sm (12), base (14), lg (16), xl (20), xxl (24). Methods: `bodySmall()`, `bodyBase()`, `bodyLarge()`, `heading()`, `headingLarge()`, `mono()`
**Radius:** sm (4), md (8), lg (12), xl (16), full (9999)
**Spacing:** xs (4), sm (8), md (16), lg (24), xl (32), xxl (48)
## Provider Setup
### OpenAI Provider
```dart
import 'flai/providers/openai_provider.dart';
final provider = OpenAiProvider(
apiKey: 'sk-your-key',
model: 'gpt-4o', // default: 'gpt-4o'
// baseUrl: 'https://your-proxy.com/v1', // optional
// organization: 'org-xxx', // optional
);
// Capabilities:
// provider.supportsToolUse == true
// provider.supportsVision == true
// provider.supportsStreaming == true
// provider.supportsThinking == false
```
### Anthropic Provider
```dart
import 'flai/providers/anthropic_provider.dart';
final provider = AnthropicProvider(
apiKey: 'sk-ant-your-key',
model: 'claude-sonnet-4-20250514', // default
// thinkingBudgetTokens: 8192, // enable extended thinking
// baseUrl: 'https://your-proxy.com', // optional
);
// Capabilities:
// provider.supportsToolUse == true
// provider.supportsVision == true
// provider.supportsStreaming == true
// provider.supportsThinking == true
```
### Using a Provider with ChatScreenController
```dart
final controller = ChatScreenController(
provider: provider,
systemPrompt: 'You are a helpful AI assistant.',
// initialMessages: [...], // optional conversation history
);
// Send a message (streams the response automatically):
await controller.sendMessage('Hello!');
// Cancel streaming:
await controller.cancel();
// Retry last failed message:
await controller.retry();
// Clear conversation:
controller.clearMessages();
// Listen to state changes:
controller.addListener(() {
print('Streaming: ${controller.isStreaming}');
print('Current text: ${controller.streamingText}');
print('Messages: ${controller.messages.length}');
});
```
### Tool Use
Define tools and send them with requests:
```dart
final tools = [
ToolDefinition(
name: 'get_weather',
description: 'Get the current weather for a location',
parameters: {
'type': 'object',
'properties': {
'location': {
'type': 'string',
'description': 'City name',
},
},
'required': ['location'],
},
),
];
final request = ChatRequest(
messages: messages,
tools: tools,
);
// Stream and handle tool call events:
await for (final event in provider.streamChat(request)) {
switch (event) {
case TextDelta(:final text):
// Append text to UI
break;
case ToolCallStart(:final id, :final name):
// Show tool call card
break;
case ToolCallDelta(:final id, :final argumentsDelta):
// Update tool call arguments
break;
case ToolCallEnd(:final id):
// Execute tool and send result back
break;
case ChatDone():
// Stream complete
break;
case ChatError(:final error):
// Handle error
break;
default:
break;
}
}
```
## Data Models
### Message
```dart
Message(
id: 'unique-id',
role: MessageRole.user, // user, assistant, system, tool
content: 'Hello!',
timestamp: DateTime.now(),
status: MessageStatus.complete, // streaming, complete, error
attachments: [...], // optional
toolCalls: [...], // optional
thinkingContent: '...', // optional (Anthropic thinking)
citations: [...], // optional
usage: UsageInfo(...), // optional
)
```
### ChatEvent (sealed class)
The streaming system uses a sealed `ChatEvent` class for type-safe event handling:
- `TextDelta(text)` -- Incremental text chunk
- `TextDone(fullText)` -- Text complete with full content
- `ThinkingStart()` -- AI began reasoning
- `ThinkingDelta(text)` -- Thinking text chunk
- `ThinkingEnd()` -- Reasoning complete
- `ToolCallStart(id, name)` -- Tool call initiated
- `ToolCallDelta(id, argumentsDelta)` -- Tool call argument chunk
- `ToolCallEnd(id)` -- Tool call complete
- `UsageUpdate(inputTokens, outputTokens, ...)` -- Token usage report
- `ChatDone()` -- Stream finished
- `ChatError(error, stackTrace?)` -- Error occurred
## Architecture Notes
- All widgets use `FlaiTheme.of(context)` to read styling -- no hardcoded colors or icons
- Components access icons via `theme.icons.send`, `theme.icons.copy`, etc.
- Components use the Widget + Controller + State pattern for complex state
- The `AiProvider` abstract class defines the interface; implementations use raw HTTP via `package:http`
- No external state management dependency -- vanilla Flutter (`ChangeNotifier`, `Stream`)
- Components are Mason bricks; the `{{output_dir}}` variable controls output location
- Zero external dependencies in core; provider bricks add `package:http`
## Starter Patterns
### Basic Chat
```bash
dart pub global activate flai_cli
flai init
flai add chat_screen openai_provider
```
```dart
FlaiTheme(
data: FlaiThemeData.dark(),
child: MaterialApp(
home: Scaffold(
body: FlaiChatScreen(
controller: ChatScreenController(
provider: OpenAiProvider(
apiKey: const String.fromEnvironment('OPENAI_API_KEY'),
model: 'gpt-4o',
),
systemPrompt: 'You are a helpful assistant.',
),
title: 'AI Chat',
),
),
),
)
```
### Multi-Model Switching
```dart
final providers = {
'GPT-4o': OpenAiProvider(
apiKey: const String.fromEnvironment('OPENAI_API_KEY'),
model: 'gpt-4o',
),
'Claude': AnthropicProvider(
apiKey: const String.fromEnvironment('ANTHROPIC_API_KEY'),
model: 'claude-sonnet-4-20250514',
),
};
// Swap provider at runtime:
void switchModel(String name) {
_controller.dispose();
setState(() {
_controller = ChatScreenController(
provider: providers[name]!,
systemPrompt: 'You are a helpful assistant.',
);
});
}
```
### Tool Calling
```dart
final controller = ChatScreenController(
provider: OpenAiProvider(
apiKey: const String.fromEnvironment('OPENAI_API_KEY'),
model: 'gpt-4o',
),
systemPrompt: 'You can look up weather.',
tools: [
ToolDefinition(
name: 'get_weather',
description: 'Get weather for a city',
parameters: {
'type': 'object',
'properties': {
'city': {'type': 'string', 'description': 'City name'},
},
'required': ['city'],
},
),
],
onToolCall: (name, args) async {
if (name == 'get_weather') {
return '{"temp": 72, "condition": "sunny"}';
}
return '{"error": "unknown tool"}';
},
);
```
### Custom Theme
```dart
final brandTheme = FlaiThemeData.dark().copyWith(
colors: FlaiColors.dark().copyWith(
primary: Color(0xFF10B981),
userBubble: Color(0xFF10B981),
userBubbleForeground: Color(0xFFFFFFFF),
),
icons: FlaiIconData.cupertino(),
typography: FlaiTypography(fontFamily: 'Inter', monoFontFamily: 'Fira Code'),
);
FlaiTheme(
data: brandTheme,
child: MaterialApp(home: ChatPage()),
)
```
## Common Patterns
### Switch Between Light and Dark Theme
```dart
class MyApp extends StatefulWidget {
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
bool _isDark = true;
@override
Widget build(BuildContext context) {
return FlaiTheme(
data: _isDark ? FlaiThemeData.dark() : FlaiThemeData.light(),
child: MaterialApp(
theme: _isDark ? ThemeData.dark() : ThemeData.light(),
home: ChatPage(
onToggleTheme: () => setState(() => _isDark = !_isDark),
),
),
);
}
}
```
### Use StreamingText Standalone
```dart
FlaiStreamingText(
text: controller.streamingText,
isStreaming: controller.isStreaming,
style: FlaiTheme.of(context).typography.bodyBase(
color: FlaiTheme.of(context).colors.foreground,
),
)
```
Or directly from a stream:
```dart
FlaiStreamingText.fromStream(
stream: provider.streamChat(request)
.whereType<TextDelta>()
.map((e) => e.text),
onStreamDone: () => print('Done!'),
)
```
### Custom Empty State
```dart
FlaiChatScreen(
controller: controller,
emptyState: Column(
mainAxisSize: MainAxisSize.min,
children: [
Image.asset('assets/logo.png', height: 64),
SizedBox(height: 16),
Text('How can I help you today?'),
],
),
)
```
### Using Theme Icons in Custom Widgets
```dart
Widget build(BuildContext context) {
final theme = FlaiTheme.of(context);
return IconButton(
icon: Icon(theme.icons.send, color: theme.colors.primary),
onPressed: onSend,
);
}
```
章节与文件索引
按说明文件中的顺序排列。
何时使用此技能
先决条件
在您的项目中初始化 FlaAI
添加组件
聊天要领
文件/命令 -> flai_init · lib/ · core/theme/ · core/models/ · providers/ai_provider.dart · flai.dart · chat_screen · flai add chat_screen
内容校验值 -> f889ee520213
当前原文的自动摘译,尚未人工审校。
何时使用此技能
用户想要将 AI 聊天 UI 添加到 Flutter 应用程序 用户询问有关 FlAI 组件(消息气泡、输入栏、流文本等) 用户需要有关 FlAI 主题(颜色、排版、间距、半径、图标)的帮助 用户想要连接到 OpenAI 或 Anthropic API 用户询问有关构建聊天屏幕、对话列表或模型选择器的信息
先决条件
Flutter 3.22+ 和 Dart 3.4+ 现有的 Flutter 项目
在您的项目中初始化 FlaAI
这将运行
flai_init程序块,在您的lib/目录中生成核心基础:core/theme/-- FlaiTheme、FlaiColors、FlaiTypography、FlaiRadius、FlaiSpacing、FlaiIconDatacore/models/-- 消息、对话、ChatEvent(密封类)、ChatRequestproviders/ai_provider.dart-- 抽象 AiProvider 接口flai.dart-- 桶导出文件添加组件
您可以一次添加多个组件:
聊天要领
组件·命令·描述
chat_screen·flai add chat_screen·带有标题、消息列表和输入栏的完整聊天屏幕。取决于:message_bubble、input_bar、streaming_text、typing_indicatormessage_bubble·flai add message_bubble· 具有用户/助理样式、思维块、工具调用芯片、引文、流式光标和错误重试的消息气泡input_bar·flai add input_bar· 带发送按钮的文本输入、附件支持、桌面上的回车发送、多行增长