ai-boss Agent SDK（Flutter）· 对接说明

把「商家经营 AI 专家」（营销专家 / 数据专家）的对话与业务卡片，以 drop-in 视图 嵌入任意 Flutter app。

版本：aiboss_agent_client 0.1.0（纯 Dart 核心）+ aiboss_agent_flutter 0.1.0（Flutter UI）。

0. 三档集成，按需选择

档 ① ② 都基于本 Flutter SDK；档 ③ 跳过 SDK 直连后端，见独立的《后端 Agent HTTP/SSE API 参考》。三档共用同一套后端，可混用（如主流程用 ①，某个页面用 ② 自绘卡片）。

1. SDK 是什么

两个包，分层：

一次接入即得：流式消息、内联 HITL（人审 / 澄清 / 补答）、营销活动卡（设计→编辑→发布→列表→详情→生命周期）、数据指标卡 + 趋势图、历史会话、三语（zh / en / ar，阿语自动 RTL）。

两个专家：

agentId 省略（null）= 走统一入口，后端路由器按用户意图自动分流到对的专家。

2. 安装

SDK 以源码包发布。pubspec.yaml 三选一：

dependencies:
  # ① 本地解压后 path 依赖（下载 tar 包解压到项目同级）
  aiboss_agent_flutter:
    path: ../packages/agent-client-flutter

  # ② git 依赖（私有仓库）
  # aiboss_agent_flutter:
  #   git:
  #     url: <repo-url>
  #     path: packages/agent-client-flutter

  # ③ 私有 pub 服务器
  # aiboss_agent_flutter: ^0.1.0

aiboss_agent_flutter 已重导出 aiboss_agent_client，只需引一个：

import 'package:aiboss_agent_flutter/aiboss_agent_flutter.dart';

• Flutter / Dart 版本：Flutter ≥ 3.x（Dart ≥ 3.0）。
• 本地化：内置 zh/en/ar 文案，无需额外配置。
• 字体：宿主自备；要正确显示中文/阿拉伯文，建议在宿主 ThemeData 配 NotoSansSC / NotoSansArabic。
• 平台：纯 Dart + Flutter widget，无平台通道；Android / iOS / Web 均可。

3. 一键集成（基础）

一个 widget，传后端地址 + 商家身份即得到完整对话页。SDK 内部托管会话生命周期，并把营销卡的确认 / 暂停 / 终止默认接到后端——宿主无需写任何 HTTP，活动「设计→编辑→发布→管理」开箱即闭环。

import 'package:aiboss_agent_flutter/aiboss_agent_flutter.dart';
import 'package:flutter/material.dart';

class PromoPage extends StatelessWidget {
  const PromoPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('营销专家')),
      body: const AiBossAgentChat(
        baseUrl: 'https://api.example.com',   // ai-boss 后端根地址
        merchantId: 'M7676177520607',          // 商家 ID
        storeId: 'B17752062199591055',         // 门店 ID（可选）
        role: 'boss',                          // 角色（默认 boss）
        agentId: 'promo-designer',             // 省略 = 统一入口自动分流
        suggestions: ['做个全单9折活动', '我有哪些活动', '搞个招牌秒杀'],
        emptyHint: '和「营销专家」对话',
      ),
    );
  }
}

就这些。 AiBossAgentChat 自己负责：建 AgentSdk + 会话、流式渲染、营销/数据卡渲染、commit/action 调后端、dispose 清理。

数据专家同理，换 agentId: 'data-analyst' + 对应 suggestions（如 ['本月净收入多少', '近7天净收入趋势']）。

想覆盖某个默认行为（如自定义普通按钮处理、或自接 commit）？AiBossAgentChat 暴露同名可选回调 onAction / onNbCampaign / onCampaignAction，传了就用你的、不传用 SDK 默认。需要更深的控制（主题、历史抽屉、卡片拆分）请用档 ②。

4. 认证与后端地址

• baseUrl：ai-boss 后端根地址（非直连 minipos / NearBoss 网关；SDK 打 ai-boss 后端，后端经连接器透传到真实业务网关）。
• 租户头：SDK 每个请求自动注入 X-Merchant-Id / X-Store-Id（scope=门店）/ X-User-Id / X-Role。merchantId = org，storeId = 门店 scope。
• 自定义鉴权（如 JWT 透传）：档 ② 实现 AuthProvider 接口注入（见 §5）。

SDK 调用的后端端点（完整请求/响应见后端 API 参考）：

5. 可定制 UI

需要套品牌主题、把会话生命周期握在自己手里、或把业务卡片拆进自有页面时，用底层组件自行装配。

class _PromoPageState extends State<PromoPage> {
  late final AgentSdk _sdk;
  late final ChatController _controller;

  @override
  void initState() {
    super.initState();
    _sdk = AgentSdk(
      config: const SdkConfig(baseUrl: 'https://api.example.com'),
      auth: HeaderAuthProvider(merchantId: 'M123', storeId: 'B1', role: 'boss'),
    );
    _controller = ChatController(_sdk.newSession(agentId: 'promo-designer'));
  }

  @override
  void dispose() {
    _controller.dispose();
    _sdk.api.close();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return AgentChatView(
      controller: _controller,
      theme: const AgentTheme(            // ← 品牌主题（见下）
        userBubble: Color(0xFF111111),
        assistantBubble: Color(0xFFF4F4F5),
        userText: Color(0xFFFFFFFF),
        assistantText: Color(0xFF111111),
        accent: Color(0xFF111111),
        cardBackground: Color(0xFFFAFAFA),
        border: Color(0xFFE4E4E7),
        radius: 14,
      ),
      l10n: AgentL10n.zh,
      suggestions: const ['做个全单9折活动', '我有哪些活动'],
      // 营销卡确认 / 动作：调 SDK 核心方法（鉴权头自动注入）
      onNbCampaign: (r) async {
        final res = await _sdk.api.nearbossCommit(
            {'surface': 'campaign', 'action': r.action, 'params': r.params});
        return res.ok
            ? NbCommitOutcome.success(res.detail)
            : NbCommitOutcome.failure(res.message ?? '提交失败');
      },
      onCampaignAction: (r) async {
        final res = await _sdk.api.nearbossCampaignAction(
            {'op': r.op, 'id': r.id, if (r.confirmed) 'confirmed': true});
        return res.ok
            ? NbCommitOutcome.success(res.detail)
            : NbCommitOutcome.failure(res.message ?? '操作失败');
      },
    );
  }
}

主题

自适应：AgentChatView 省略 theme 时，自动从宿主 Theme.of(context).colorScheme 派生 AgentTheme.fromContext(context)——跟随宿主品牌色 / 深浅模式。

显式覆盖：传 AgentTheme(...)，8 个 token：

国际化 + RTL

AgentChatView(l10n: AgentL10n.zh | .en | .ar)。传 .ar 自动 RTL 镜像。省略则取 AgentLocalizations.of(context)，回退 zh。

自定义鉴权

class JwtAuthProvider implements AuthProvider {
  @override
  Future<Map<String, String>> headers() async => {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ${await fetchToken()}',
  };
  @override String chatPath() => '/api/v1/agent/chat';
  @override String userTextKey() => 'message';
  @override String agentIdKey() => 'agent_id';
}

业务卡片单独使用

9 个卡件均可脱离 AgentChatView 单独嵌入自有页面：ActionCardView（按 form.kind 自动路由分发）、NbCampaignFormView（可编辑草稿）、NbTypePickerView（类型选择）、NbCampaignListView（活动列表）、NbCampaignDetailView（详情 + 生命周期）、ChartView、MessageBubble、AgentHistoryDrawer、Composer。各自接收对应协议对象 + AgentTheme + 回调。

6. 业务卡系统（营销专家）

营销活动全流程由 SDK 卡件渲染，对话里出现哪种卡由后端按 form.kind 决定：

4 类活动（注意枚举名与直觉相反，权威定义见后端 API 参考 活动类型节）：

确认 / 动作的两种接法：

• 档 ①（一键）：AiBossAgentChat 已默认接好，无需写代码。
• 档 ②（可定制）：传 onNbCampaign / onCampaignAction，内部调 sdk.api.nearbossCommit(...) / nearbossCampaignAction(...)（见 §5 代码）。返回 NbCommitOutcome 决定卡片切「已发布」态或就地红字报错。

生命周期按钮由后端返回的 availableActions 驱动（按状态 DRAFT / PENDING / ACTIVE / PAUSED / ENDED）。SDK 只渲染开放的 PAUSE / RESUME / TERMINATE；TERMINATE 须二次确认（首次返回 AIGENT_CONFIRM_REQUIRED，带 confirmed: true 重提）。

7. 数据卡（数据专家）

数据专家返回的卡含 indicators（指标行）+ 可选 chart（趋势折线 / 环比柱）。SDK ActionCardView 自动渲染，无需宿主回调。

• 指标全部来自接口（零推算原则，SDK 与后端都不自算数字）。
• 数据专家答 3 指标域：净收入 / 成功交易 / 退款；趋势走 chart（line，7 点）。

8. 会话与历史

sdk.newSession(agentId: ..., conversationId: ...); // 新会话
sdk.resumeSession(conversationId, agentId: ...);   // 带 id 续聊（不预载）
await sdk.openConversation(conversationId);          // 拉历史消息种入新会话，可继续追问
sdk.api.listConversations();                         // 历史会话列表 REST
sdk.api.listMessages(conversationId);                // 历史消息 REST

AgentHistoryDrawer（history_list.dart）可直接放进 Scaffold.endDrawer 做历史会话抽屉。

9. 错误处理

完整错误码表见后端 API 参考。

10. 故障排查（FAQ）

Q：卡片不出，只有纯文字回答？ A：确认 agentId 传对（promo-designer / data-analyst），且后端 AIBOSS_BIZ_PROFILE=nearboss（否则走 mock 档，字段/语言不同）。

Q：活动「确认发布」点了没反应 / 报「网络错误」？ A：档 ① 已内置 commit；档 ② 检查 onNbCampaign 是否真的调了 sdk.api.nearbossCommit。statusCode==0 表示根本没连上后端——查 baseUrl 与网络可达性。

Q：返回 401 / 无权限？ A：缺 X-Merchant-Id。一键档确认传了 merchantId；自定义 AuthProvider 确认 headers() 带齐租户头。

Q：中文 / 阿拉伯文显示成方框？ A：宿主未配覆盖该字符集的字体。在 ThemeData 里配 NotoSansSC / NotoSansArabic。

Q：流式回答中途断了？ A：SSE 长连接受代理 / 网关超时影响。后端 /agent/chat 读超时建议 ≥ 300s；若经 nginx 反代，关 proxy_buffering。

Q：阿语界面没有 RTL？ A：传 l10n: AgentL10n.ar（一键档传 l10n 参数）。SDK 据此自动 Directionality.rtl。

11. 公开 API 速查

aiboss_agent_client（纯 Dart）：AgentSdk · SdkConfig · AuthProvider / HeaderAuthProvider / BearerAuthProvider · ChatSession（.send / .states / .phase）· AgentApi（nearbossCommit / nearbossCampaignAction / listConversations / listMessages / sendFeedback / recallMemory）· NbCommitResult · ActionCard / ActionButton / Indicator / ChartSpec · 协议事件模型。

aiboss_agent_flutter（含上者全部）：AiBossAgentChat（一键门面）· AgentChatView（drop-in）· ChatController · AgentTheme · AgentL10n / AgentLocalizations · 卡件 ActionCardView / NbCampaignFormView / NbCampaignListView / NbCampaignDetailView / NbTypePickerView / NbProductPickerSheet / ChartView / ClarifyView / MessageBubble / Composer / AgentHistoryDrawer / MarkdownText。回调结果：NbCampaignResult / NbCampaignActionResult / NbCommitOutcome / CampaignFormResult。

12. 版本

0.1.0 起新增一键门面 AiBossAgentChat + 核心 AgentApi.nearbossCommit / nearbossCampaignAction。

不用 Flutter？完全自定义 UI 直连后端见《后端 Agent HTTP/SSE API 参考》。问题 / 对接支持联系 ai-boss 团队。