Flutter插件murmuration的使用方法

Flutter插件murmuration的使用方法

Murmuration (2.0.0) 🐦✨

一个强大的Dart框架，用于使用Google的生成式AI模型来协调多代理交互。Murmuration 提供类型安全、线程安全且可靠的系统，用于代理协调、状态管理和函数执行。

[⚠️警告] 如果计划在生产环境中使用此插件，请确保有适当的错误处理和测试，因为与AI模型的交互可能不可预测。

名称“Murmuration”灵感来源于鸟群的迷人飞行行为，象征着框架的重点在于协调代理交互和动态工作流程。 🐦💫

Murmuration 2.0.0 新增功能 🐦

版本2.0.0引入了强大的新功能和增强，以提高你在使用Murmuration时的体验：

• 增强的模式验证：重新设计以提高类型安全性并更严格的验证。
• 线程安全的状态管理：具有类型安全访问方法的不可变状态。
• 改进的错误处理：新的MurmurationException类，用于详细的错误见解。
• 消息历史更新：持久的、线程安全的存储，并自动清理。
• 新的配置选项：缓存支持、重试策略等。
• 流响应增强：更好的并发性和进度跟踪。

突破性变化

此版本包含可能需要更新你的实现的重大更改。请参阅迁移指南以获取平滑升级的详细步骤。

目录 📚

• 概述
• 安装
• 核心功能
• 使用指南
  • 基本用法
  • 高级用法
  • 流响应
  • 模式验证
  • 状态管理
  • 代理链
• 架构概述
• 核心系统
• 真实世界示例
• 故障排除
• 最佳实践
• 贡献
• 教程
• 许可证
• 作者

概述 🔍

Murmuration 提供：

• 类型安全的模式验证系统，以确保数据完整性
• 线程安全的状态管理，以防止竞态条件
• 强大的错误处理，带有详细的错误报告
• 具有持久性的消息历史管理
• 工具和函数集成，以扩展功能
• 代理链编排，以处理复杂的工作流程
• 流响应支持，以实现实时处理
• 综合日志记录，用于调试和监控

安装 ⚙️

在你的 pubspec.yaml 中添加以下依赖：

dependencies:
  murmuration: ^2.0.0
  google_generative_ai: ^latest_version
  shared_preferences: ^latest_version
  synchronized: ^latest_version

然后运行：

dart pub get

核心功能 🛠️

配置

final config = MurmurationConfig(
  apiKey: 'your-api-key',
  model: 'gemini-1.5-pro',  // 指定要使用的模型
  debug: true,              // 启用调试模式以启用详细的日志记录
  stream: false,            // 默认禁用流
  logger: MurmurationLogger(enabled: true),  // 启用日志记录
  timeout: Duration(seconds: 30),  // 设置请求超时时间
  maxRetries: 3,           // 重试次数
  retryDelay: Duration(seconds: 1),  // 重试之间的延迟
  enableCache: true,       // 启用响应缓存
  cacheTimeout: Duration(hours: 1)  // 缓存过期时间
);

错误处理

Murmuration 使用 MurmurationException 类进行错误处理。这允许你在代理执行期间优雅地捕获和处理错误。例如：

try {
  final result = await agent.execute("Process data");
} on MurmurationException catch (e) {
  print('Error: ${e.message}');  // 易读的错误信息
  print('Original error: ${e.originalError}');  // 原始异常
  print('Stack trace: ${e.stackTrace}');  // 完整堆栈跟踪
}

日志记录

你可以使用 MurmurationLogger 类启用日志记录以跟踪事件和错误：

final logger = MurmurationLogger(
  enabled: true,
  onLog: (message) => print('Log: $message'),  // 日志处理器
  onError: (message, error, stackTrace) {      // 错误处理器
    print('Error: $message');
    print('Details: $error');
  }
);

架构概述 🏗️

Murmuration 是建立在几个核心系统之上，这些系统协同工作以提供一个健壮的框架：

1. 核心系统

   • 错误处理系统：管理异常和错误报告
   • 模式验证系统：确保数据完整性
   • 状态管理系统：处理线程安全的状态更新
   • 消息历史系统：管理对话上下文
   • 日志系统：跟踪事件和错误
   • 配置管理：处理框架设置
   • 代理管理：协调AI模型交互
   • 工具和功能管理：处理外部集成
   • 执行和进度跟踪：监控工作流程状态

2. 关键组件

   • Murmuration：主类，负责协调所有组件
   • Agent：核心类，处理AI模型交互
   • MurmurationConfig：配置管理
   • MessageHistory：线程安全的消息管理
   • ImmutableState：线程安全的状态管理
   • SchemaField：类型安全的验证系统

核心系统 🔧

1. 消息历史

线程安全的消息管理，带持久化：

final history = MessageHistory(
  threadId: 'user-123',       // 唯一线程标识符
  maxMessages: 50,            // 最大保留的消息数
  maxTokens: 4000             // 总的最大令牌数
);

await history.addMessage(Message(
  role: 'user',
  content: 'Hello!',
  timestamp: DateTime.now()
));

await history.save();    // 持久化到存储
await history.load();    // 从存储加载
await history.clear();   // 清除历史记录

2. 状态管理

线程安全、不可变的状态操作：

final state = ImmutableState()
  .copyWith({
    'user': {'name': 'John', 'age': 30},
    'preferences': {'theme': 'dark'}
  });

final userName = state.get<String>('user.name');  // 类型安全访问

使用指南 📖

基本用法

void main() async {
  final murmur = Murmuration(config);

  final agent = await murmur.createAgent(
    {'role': 'Assistant', 'context': 'Data processing'},
    currentAgentIndex: 1,
    totalAgents: 1
  );

  final result = await agent.execute("Process this data");
  print(result.output);
}

高级用法

自定义模式字段

class DateTimeSchemaField extends SchemaField<DateTime> {
  final DateTime? minDate;
  final DateTime? maxDate;

  const DateTimeSchemaField({
    required String description,
    this.minDate,
    this.maxDate,
    bool required = true,
  }) : super(
    description: description,
    required: required,
  );

  @override
  bool isValidType(Object? value) =>
    value == null ||
    value is DateTime ||
    (value is String && DateTime.tryParse(value) != null);

  @override
  bool validate(DateTime? value) {
    if (value == null) return !required;
    if (minDate != null && value.isBefore(minDate!)) return false;
    if (maxDate != null && value.isAfter(maxDate!)) return false;
    return true;
  }

  @override
  DateTime? convert(Object? value) {
    if (value == null) return null;
    if (value is DateTime) return value;
    if (value is String) return DateTime.tryParse(value);
    return null;
  }
}

// 使用示例：
final schema = OutputSchema(
  fields: {
    'name': StringSchemaField(
      description: 'User name',
      minLength: 2,
      required: true
    ),
    'birthDate': DateTimeSchemaField(
      description: 'Birth date',
      minDate: DateTime(1900),
      maxDate: DateTime.now(),
      required: true
    )
  }
);

流响应 🌊

final config = MurmurationConfig(
  apiKey: 'your-api-key',
  stream: true  // 启用流
);

final agent = await murmur.createAgent({'role': 'Assistant'});
final result = await agent.execute("Generate a long story");

if (result.stream != null) {
  await for (final chunk in result.stream!) {
    print(chunk);  // 每个到达的块进行处理
  }
}

代理链 ⛓️

文档处理链的例子：

final result = await murmur.runAgentChain(
  input: documentText,
  agentInstructions: [
    {
      'role': 'Document Parser',
      'context': 'Extract key information from documents'
    },
    {
      'role': 'Data Analyzer',
      'context': 'Analyze and categorize extracted information'
    },
    {
      'role': 'Report Generator',
      'context': 'Generate comprehensive report'
    }
  ],
  tools: [
    Tool(
      name: 'document_parser',
      description: 'Parses document text',
      parameters: {'text': StringSchemaField(description: 'Document text')},
      execute: (params) async => parseDocument(params['text'])
    )
  ],
  functions: {
    'analyze': (params) async => analyzeData(params),
    'generate_report': (params) async => generateReport(params)
  },
  logProgress: true,
  onProgress: (progress) {
    print('Progress: ${progress.currentAgent}/${progress.totalAgents}');
    print('Status: ${progress.status}');
  }
);

print('Final report: ${result.finalOutput}');

真实世界示例 💡

客户支持机器人

final supportBot = await murmur.createAgent({
  'role': 'Customer Support',
  'context': '''
    You are a helpful customer support agent.
    Follow company guidelines and maintain professional tone.
    Escalate sensitive issues to human support.
  '''
});

// 添加票务管理工具
supportBot.addTool(Tool(
  name: 'create_ticket',
  description: 'Creates support ticket',
  parameters: {
    'priority': StringSchemaField(
      description: 'Ticket priority',
      enumValues: ['low', 'medium', 'high']
    ),
    'category': StringSchemaField(description: 'Issue category')
  },
  execute: (params) async => createSupportTicket(params)
));

final response = await supportBot.execute(userQuery);

数据处理流水线

final pipeline = await murmur.runAgentChain(
  input: rawData,
  agentInstructions: [
    {'role': 'Data Validator'},
    {'role': 'Data Transformer'},
    {'role': 'Data Analyzer'},
    {'role': 'Report Generator'}
  ],
  tools: [
    Tool(
      name: 'data_validation',
      description: 'Validates data format',
      execute: validateData
    ),
    Tool(
      name: 'data_transform',
      description: 'Transforms data format',
      execute: transformData
    )
  ]
);

故障排除 🔍

常见问题

1. 超时错误

   // 增加超时时间
   final config = MurmurationConfig(
     timeout: Duration(minutes: 2),
     maxRetries: 5
   );
   

2. 内存问题

   // 管理消息历史
   final config = MurmurationConfig(
     maxMessages: 30,
     maxTokens: 2000
   );
   

3. 状态管理问题

   // 正确使用状态复制
   final newState = state.copyWith(newData);
   // 不要直接修改状态
   state._data['key'] = value;  // 错误！