30 KiB
AI_Chat_Assistant PRD
AI 聊天助手需求设计文档（产品需求文档 PRD）
文档介绍
| 项目 | 信息 |
|---|---|
| 产品名称 | AI Chat Assistant Flutter Plugin |
| 版本 | v1.0.0+1 |
| 文档版本 | v1.0 |
| 创建日期 | 2025-09-23 |
| 最近更新时间 | 2025-09-24 |
| 产品经理 | （待指定） |
| 技术负责人 | （待指定） |
| 目标平台 | Flutter (Android / iOS，首期 Android 优先) |
| 发布形态 | Flutter 第三方插件（支持示例 App） |
修订记录
| 版本 | 日期 | 作者 | 内容 |
|---|---|---|---|
| 1.0 | 2025-09-23 | - | 初版功能需求整理 |
1. 引言
1.1 文档目的
本文档旨在定义“AI Chat Assistant Flutter Plugin”项目的详细功能需求、非功能需求、技术架构及项目规划。它为设计、开发、测试及项目相关人员提供了统一的参考依据和验收标准。
1.2 适用范围
本文档目标读者为：AI Chat Assistant Flutter Plugin 的系统设计人员、开发人员、测试人员、产品经理以及项目管理人员。
1.3 名词解释
| 序号 | 名词术语 | 名词解释 |
|---|---|---|
| 1 | Flutter Plugin | 一种可复用的代码包，用于为Flutter应用添加特定的原生平台功能。 |
| 2 | ASR | Automatic Speech Recognition，自动语音识别，将语音转换为文本。 |
| 3 | TTS | Text-To-Speech，语音合成，将文本转换为语音。 |
| 4 | SSE | Server-Sent Events，一种服务器向客户端推送数据的技术。 |
| 5 | 车控命令 | 通过语音或界面触发的，用于控制车辆功能（如门锁、空调）的指令。 |
| 6 | 场景（Scenario） | 不同业务上下文（购车 / 用车） |
1.4 统一异常处理
- 网络异常：语音识别或AI对话过程中出现网络错误，应有明确提示（如：“网络连接失败，请检查后重试”），并提供重试选项。
- 权限拒绝：当未授予麦克风或音频录制权限时，应引导用户前往系统设置开启权限。
- 语音识别失败：返回空文本或低置信度，提示“抱歉，我没有听清，请再说一遍”。（补充：不缓存失败结果。）
- 命令执行失败：车控执行失败需双通道反馈（UI + TTS），并显示失败原因或错误类型标签。（补充：通用错误尽量转化为用户友好语义。）
2. 产品概述
2.1 产品简介
AI Chat Assistant 是一个集成语音识别、智能对话、车控指令解析与执行、语音反馈渲染于一体的 Flutter 插件。支持“车控助手”与“用车助手”双场景：
- 车控助手：支持 20+ 车辆控制命令（如空调、车窗、车门、座椅加热等）。
- 用车助手：基于用户手册 / 知识库进行问答。（包含 保养咨询、能耗优化建议等）
- 购车助手：基于厂家的经销政策以及车辆配置信息进行问答
2.2 产品流程图
现有核心流程：用户长按语音按钮 → 权限校验 → 录音 + 识别 → 文本分类 → 路由到问答/车控/错误反馈 → 结果播报与展示。
graph TD
A[用户点击语音按钮] --> B[startVoiceInput]
B --> C[检查麦克风权限]
C --> D[开始录音/ASR]
D --> E[实时显示识别结果]
E --> F[用户松开按钮]
F --> G[stopAndProcessVoiceInput]
G --> H[调用reply处理文本]
H --> I[文本分类]
I --> J{分类结果}
J -->|车控命令| K[handleVehicleControl]
J -->|普通问答| L[answerQuestion - ChatSseService]
J -->|错误问题| M[answerWrongQuestion]
K --> N[解析车控命令]
N --> O[执行TTS播报]
O --> P[执行车控命令]
P --> Q[生成执行反馈]
Q --> R[更新UI显示]
L --> S[SSE流式对话]
S --> T[实时TTS播报]
T --> R
2.3 产品目的
- 提供开箱即用的AI语音交互能力
- 支持自然语言车控命令识别与执行
- 轻量级架构，易于集成和定制
2.4 顶层功能结构
graph LR
ASR[语音采集/ASR] --> CLASS[文本/意图分类]
CLASS -->|车控| CMD[车控解析/执行]
CLASS -->|问答| QA[对话引擎 SSE/WS]
CLASS -->|兜底| FALL[引导重试/澄清]
QA --> TTS[TTS 播报]
CMD --> FEED[执行反馈]
TTS --> MSG[消息渲染]
FEED --> MSG
MSG --> STORE[(本地持久化)]
2.5 语音交互主流程
graph TD
START[长按/唤醒触发] --> PERM[权限校验]
PERM -->|通过| REC[开始录音]
PERM -->|拒绝| EXIT[权限引导提示]
REC --> ASR[实时增量识别]
ASR --> RELEASE[松手/结束]
RELEASE --> CLASSIFY[分类/意图识别]
CLASSIFY -->|车控| CONTROL[结构化命令]
CLASSIFY -->|问答| STREAM[流式对话输出]
CLASSIFY -->|无匹配| GUIDE[兜底提示]
CONTROL --> EXEC[调用车控处理器]
EXEC --> RESULT[结果反馈]
STREAM --> MERGE[增量合并/渲染]
RESULT --> RENDER[消息渲染 + TTS]
MERGE --> RENDER
RENDER --> STORE[(持久化过滤保存)]
3. 功能需求
3.1 用户页面展示
3.1.1 浮动图标组件（ChatFloatingIcon）
- 用户场景
在主应用界面上提供一个常驻的、可随意拖拽的AI助手入口，作为全局统一入口，维持轻量可达性，不干扰主业务操作。
- 功能描述
一个可拖拽的浮动按钮，点击展开全屏聊天界面，长按直接启动语音输入（只有聊天窗口）。
- 需求说明
-
拖拽吸附：支持在屏幕内自由拖拽，松开时自动吸附到最近的屏幕边缘。
-
交互响应：
- 点击： 进入全屏的聊天页面，全屏模式为一个新的页面
- 长按：变为聆听模式，直接开始语音录制，出现聊天窗口
- 位置自适应：聊天窗口的位置需要根据浮动按钮的位置变化，如果浮动按钮位置过于靠上，则聊天窗口显示在浮动按钮的下方，默认显示在浮动按钮的上方
-
状态指示：通过动画（如呼吸效果）表示待机、聆听、思考等不同状态。
默认为待机状态，长按会进入聆听状态，思考中的状态会在聊天显示思考中的状态聊天气泡
-
补充说明：长按阈值建议 300ms；误触策略：短按抬起不触发录音。
-
3.1.2 浮动聊天窗口（ChatPopup）
- 用户场景
用户与AI助手进行可视化的文本和语音交互。
- 功能描述
提供弹出式聊天窗口，展示对话记录并提供输入方式，不承担复杂历史翻阅与批量操作
- 需求说明
长按浮动按钮即可出现浮动聊天窗口，长按状态下展示聆听中，放开后则聆听结束，变为思考中状态。
思考中状态可以手动点击 停止回答 可以终止AI对话，直到回答完成，则不可点击停止回答。
3.1.3 全屏聊天界面（ChatFullscreen）
- 用户场景
用户与AI助手进行可视化的文本和语音交互，适用于长对话、多轮引用、查看历史与多类型气泡的交互。
- 功能描述
提供全屏聊天界面，展示对话记录并提供输入方式。全屏的聊天页面功能更加丰富，多类型气泡、快捷指令区、功能按钮区、历史分页加载
- 需求说明
- 全屏聊天模式下会保留之前浮动聊天窗口的聊天记录
- 不同的场景为不同的AI助手，现有两种场景，购车助手和用车助手(根据入口来判断)
- 顶部会有可配置的功能按钮区域（用户服务/购车服务）
- 功能按钮下方会有快捷对话的区域，可以点击换一换来更换快捷指令，支持“换一换”刷新策略（本地轮换或服务侧下发）
- 聊天页面底部会有功能栏，分别为删除当前对话，按住说话，切换文本输入
- 如果存在本地对话记录，点击 显示历史对话记录 会加载之前的5条对话记录，同样可以通过上拉来加载历史对话记录
3.2 AI对话场景
3.2.1 购车助手场景
- 用户场景
用户未绑定车辆的情况下，爱车页面变为购车页面，购车页面也会有AI助手，未绑定车辆用户获取车型配置、优惠、推荐。
- 功能描述
购车页面的AI助手没有聆听模式，只能点击进入全屏的聊天页面，首次的回复词也会有变化；功能按钮区域和快捷回复区域都会跟用车助手不同
- 需求说明
- 浮动按钮点击可进入全屏的AI助手页面，顶部的功能按钮为热门车型推荐，同样是icon+text的按钮，点击之后会快捷输入车型的名称，AI助手会回复车型的相关信息，同时快捷对话的区域会按照对话来进行变化；
- 购车助手同样可以通过文本的语义来进行推荐车型，以及解读购车的优惠信息；
- 如果在购车助手场景下，本身并没有绑定车辆，如果有车控的语音输入，则返回：您还未绑定车辆，无法使用车控指令；
- 如果是用车助手场景，包含购车助手的全部功能，同样可以回复相应车型来获取配置信息以及购车政策。
3.2.2 用车助手场景
- 用户场景
用户在绑定车辆的情况下，进入爱车页面，使用AI助手则我用车助手场景
- 功能描述
用车助手场景下的AI助手不同于购车场景，可以按照文本的输入分为三种：普通问答，车控指令，错误问题反馈
- 需求说明
- 用车场景下的功能按钮为官方推荐，内容包括智能场景推荐、数据埋点和运营位，其中智能场景推荐包括售后维保提醒，智能场景建议；数据埋点包括能耗报告，行为分析，用户习惯操作；运营位则是推荐的车型，用户复购建议；
- 常见功能按钮 → 发送一条“功能集合”消息气泡（含多个按钮）。
- 点击 更多工具按钮跟常见功能按钮一样，会返回一条聊天记录，里面会包含多个按钮，点击按钮可以进行快捷回复；
- 快捷回复区域是可以变化的，会根据对话的最后一个回复进行变化，快捷回复区域会跟在最后一个对话的底部；例如刚进入会跟在 功能按钮的底部，但是新的聊天记录出现后，就会自动拼接到聊天气泡的底部（聊天气泡类型分为多种，后面会详细介绍）；
3.2.3 用户唤醒场景
- 用户场景
在开通语音唔醒功能之后，购车页面和爱车页面都可以使用语音唤醒，免手动触发，提高便利性
- 功能描述
用户可以通过语音唤醒功能在不需要点击按钮的情况下激活AI助手，提高使用便捷性和用户体验。唤醒词“你好，众众”，唤醒后直接进入聆听模式并高亮反馈。
- 需求说明
- 设置页开启后常驻监听（低功耗策略）。
- 唤醒检测在本地执行，未唤醒音频不上传。
- 唤醒成功：音效 + 动画反馈。
- 低电量模式：可自动降敏或暂停。
- 权限缺失：首次引导开启麦克风权限。
3.3 聊天模块
3.3.1 聊天气泡类型
- 用户场景
用户与AI助手对话过程中，会展示不同类型的聊天气泡以适应各种交互需求。
- 功能描述
系统支持多种聊天气泡类型，包括文本气泡、卡片气泡、按钮气泡、链接气泡和富媒体气泡等，以满足不同场景下的交互需求。
- 需求说明
- 文本气泡：展示普通文字对话内容，完整支持Markdown格式； Markdown支持包括普通文本格式化、表格布局以及图片嵌入，提供更丰富的内容展示方式
- 卡片气泡：用于展示结构化信息，如车辆信息、维保记录等；
- 按钮气泡：包含可交互按钮，用于快速回复或执行操作；
- 富媒体气泡：支持图片、视频、语音等多媒体内容展示； 富媒体气泡可能适用于显示特定的信息，或者是视频的教程，轮播的图片
- 链接气泡：用于显示一个链接，包含Icon，Title，Description，以及一个可以点击的链接； 点击链接可以进入webview，链接气泡主要是用于详细介绍某些活动或者查看详情
- 业务气泡：用于特定业务的定制化气泡，会根据对话的业务场景，显示不同的气泡。 业务气泡不同于其他的气泡，可以在用户询问金融方案后显示返回的计算结果，在结果后面还有一个按钮，可以进入金融计算器的页面；同时在用户说出我希望订购某款车型时，会出现车型的信息，并且有一个立即订购的按钮。业务气泡是根据返回的数据来判断具体的业务场景，混合显示的气泡类型。
3.3.2 普通问答流程
- 用户场景
用户与AI助手对话过程中，AI助手会把语音转换为文本，通过文本的语义来判断场景，是普通问答或者是车控指令
- 功能描述
普通问答现在只有用车助手这个场景，后续增加新的场景：购车助手；需要先通过文本语义判断是哪个场景，然后根据相应场景来回复问题。
- 需求说明
- 场景识别由后端完成，前端仅消费分类结果
- SSE：按流片段累积，合并为 Markdown
不管是购车场景还是用车场景，或者是开放式对话，都有一个问答的流程，场景的区分不是前端来判断。现在流程是将语音转化的文本通过接口发给后台服务，然后后台会根据body里面的text和conversation_id 来返回一个文件流，客户端这边会把文件流的全部数据接受完成后合并为一个markdown语法的文本。
graph TD
A[文本数据] --> B{Chat api}
B --> C[文件流] --> D{SSE Service} --> E[Markdown文本]
E --> F{TTS} --> G[播放语音]
E --> H{Message} --> I[显示]
现在有两个新的调整方案，一个是Socket连接，另外一个方案是在现有的流程基础上新增消息类型。
- Socket方案
每次进入AI助手会话会创建一个随机的taskId，然后每次对话都会有一个conversationId，使用taskId 连接Socket成功后，就可以通过Socket发送语音或者文本消息。然后Socket 会返回三种不同的消息类型，it消息 (识别文本)，gb消息 (回复文本)，tts消息 (语音数据)。
流程图如下：
sequenceDiagram
participant C as 客户端
participant S as 服务器
Note over C, S: 第一步：建立WebSocket连接
C->>S: WebSocket Handshake (携带认证信息)
Note over C, S: 第二步：客户端发送语音数据
C->>S: 发送消息: {taskId, conversationId, audioData}
Note over C, S: 第三步：服务器异步返回多条消息
par 并行处理与推送
S-->>C: it消息 (识别文本)
and
S-->>C: gb消息 (回复文本)
and
S-->>C: tts消息 (语音数据)
end
Note over C, S: 连接保持，可继续发送新语音或关闭
- HTTP方案
HTTP方案是保持原有流程的情况下进行扩展，chat API 不再是返回一个数据流，而是返回一个json数据，json数据里面会有不同的消息返回，对应上面不同的气泡类型，消息类似分为stream，text，media，bussines，stream消息就是之前的数据流的消息，通过messageId就可以获取到数据；text消息是普通的文本消息，可以实现上面的链接气泡，按钮气泡；media消息则可以实现负责的图文混排，或者是一个单纯的视频教程；bussines消息主要以业务相关的，会根据业务类型显示不一样的样式，内容和按钮也会有变化。
{
"conversationId": 1,
"taskId": "task_123",
"code": 200,
"scenario": "buying_assistant",
"messageList": [
{
"messageId": "messageId_xxxxx",
"type": "stream"
},
{
"messageId": "messageId_xxxxx",
"type": "text",
"content": "xxxxx"
},
{
"messageId": "messageId_xxxxx",
"type": "media"
},
{
"messageId": "messageId_xxxxx",
"type": "bussines",
"bussineType": "vehicle_commendation"
},
]
}
3.3.3 车控指令流程
- 用户场景
用户与AI助手对话过程中，AI助手会把语音转换为文本，通过文本的语义来判断场景，是普通问答或者是车控指令
- 功能描述
如果根据分类结果，将语音或者文本信息归类为车控指令，则会进入车控指令的流程。识别语音指令中的车控意图，解析参数，并调用相应的车辆控制接口。
- 需求说明
- 命令识别：支持识别20+种车控命令类型。
- 参数解析：能从指令中解析出关键参数（如温度值、座椅位置）。
- 执行反馈：命令执行成功或失败，都必须有明确的TTS和UI反馈。
- 可扩展性：提供抽象类
VehicleCommandHandler，允许开发者根据具体车型实现自定义控制逻辑。 - 支持命令示例：
- 车门控制：上锁、解锁
- 车窗控制：开启、关闭
- 空调控制：开启、关闭、温度调节、极速降温
- 座椅控制：主/副驾驶座椅加热、通风
- 后备箱控制：开启、关闭
- 特殊功能：鸣笛、车辆定位、一键备车、一键融雪
3.3.4 聊天信息持久化
- 用户场景
用户在与AI助手进行对话时，会产生多条聊天记录。为保护用户隐私和提升体验，这些聊天记录默认仅保存在本地设备，不会上传至云端。
- 功能描述
系统支持本地化持久化存储普通问答类型的聊天记录。所有文本类消息将以结构化数据形式保存至本地数据库（推荐使用SQLite或Hive等Flutter主流轻量级数据库），便于后续检索和管理。
- 需求说明
- 本地存储：所有与AI助手的聊天记录（包括文本、语音、气泡类型、时间戳等）需保存在本地设备，支持持久化；
- 存储方式：采用本地数据库（如SQLite、Hive等Flutter常用方案），或文件存储，保证数据安全和高效读写；
- 读取与展示：用户重新进入聊天界面时，不会自动加载历史聊天记录，点击显示历史记录之后才会加载聊天记录，按时间顺序展示；
- 数据结构：每条聊天记录需包含：消息ID、会话ID、消息类型（文本/语音/卡片/按钮/富媒体）、内容、时间戳、发送方（用户/AI）、气泡类型等；
- 删除与清理：支持用户手动删除单条或全部聊天记录，支持定期自动清理（如超过30天自动删除）；
- 持久化逻辑：在Socket和HTTP两种消息方案下，收到消息体后，系统会优先将stream和text类型消息持久化保存，其他类型消息仅用于即时展示，不做持久化处理。
有了消息的持久化，AI助手聊天消息的显示逻辑也会跟着变化，按照上面的Socket方案和HTTP方案，收到消息体之后首先会保存到本地，特别是HTTP方案中会有多条消息返回，持久化只会保存stream和text消息，其他消息不会保存。
graph TD
A[收到AI助手消息] --> B[显示消息到聊天界面]
B --> C{消息类型判断}
C -->|stream/text| D[持久化保存到本地数据库]
C -->|其他类型| E[仅显示，不持久化]
D --> F[历史消息管理]
F --> G[用户点击显示历史记录]
G --> H[加载历史消息并展示]
4. 非功能需求
4.1 服务模块
4.1.1 模块设计目标
服务模块负责“输入 → 解析 → 对话/车控 → 反馈 → 持久化”全链路的能力封装，向上提供简单一致的编程接口，向下屏蔽多种后端形态（HTTP / SSE）与原生能力（录音、TTS、权限、ASR）。
设计目标：
- 解耦：各服务单一职责，可独立替换；
- 可扩展：新协议 / 新命令 / 新气泡类型通过注册或策略扩展；
- 可裁剪：按需选择（如不需要车控，可不接入 command 子模块）。
4.1.2 模块目录设计
拟将现有核心服务抽离为独立基础包（例如：ai_chat_core），供 UI 插件依赖。
建议目录结构：
packages/
ai_chat_core/
lib/
ai_chat_core.dart # 对外统一入口
src/ # 代码目录
models/ # models
message.dart # 消息和消息块
message_chunk.dart
vehicle_command.dart # 车控
vehicle_command_response.dart
command_result.dart
enums/ # enums
message_type.dart
message_status.dart
command_type.dart
service_state.dart # 服务状态
input/
audio_recorder_service.dart # 录音以及保存文件
voice_recognition_service.dart # 目前项目未使用
wake_word_service.dart # 预留（可选）
nlp/ # 自然语言处理相关
text_classification_service.dart
vehicle_command_service.dart
dialog/ #对话相关的
chat_channel/
chat_sse_service.dart # SSE
chat_ws_service.dart # 预留 WebSocket（可选）
chat_http_service.dart # 批量 HTTP 方案（可选）
message_service.dart # 核心编排/状态更新
tts/ # TTS
tts_service.dart
tts_task_queue.dart
command/ # 车控相关
command_service.dart # Command Register Callback（已更新为抽象类的方式）
vehicle_command_handler.dart # 自定义实现车控命令
persistence/ # 持久化
persistence_service.dart # 提供持久化服务
dao/ # dao
message_dao.dart # 消息体的 dao 对象
infra/ # infra 的服务
config_service.dart
redis_service.dart
location_service.dart
vehicle_state_service.dart # 预留
logger.dart
error_mapper.dart
utils/ # 工具类
markdown_cleaner.dart
id_generator.dart
throttle.dart
对外暴露（ai_chat_core.dart）仅导出：
- models / enums
- MessageService（主入口）
- VehicleCommandHandler 抽象
- 配置初始化（initCore / setConfig）
4.1.3 核心服务说明
| 服务 | 角色 | 主要职责 | 关键点 |
|---|---|---|---|
| MessageService | 总编排 | 状态机、消息生命周期、调用链调度 | 统一入口 |
| AudioRecorderService | 输入 | 录音启动/停止、静音检测 | 录制参数配置 |
| VoiceRecognitionService | 输入处理 | 语音转文本（在线识别 / 中英判别） | 失败降级提示 |
| WakeWordService | 输入唤醒 | 本地唤醒词检测 | 低功耗策略 |
| TextClassificationService | 语义分类 | 业务场景 / 指令 / 问答判断 | 分类缓存 |
| VehicleCommandService | 语义→结构 | 解析多条车控命令列表 + 参数 | 容错解析 |
| CommandService | 执行派发 | 调用 Host 注入的 VehicleCommandHandler | 失败重试 |
| ChatSseService | 对话通道 | SSE 流接收与分片回调 | 首 Token 优化 |
| ChatWsService（预留） | 对话通道 | WebSocket 统一多类型消息 | 心跳+重连 |
| ChatHttpService（预留） | 对话通道 | 一次性批量消息 | 并行补拉 |
| TtsService + TtsTaskQueue | 输出播报 | 分句 / 排队 / 抢占 / 语言切换 | 顺序一致性 |
| PersistenceService | 持久化 | 消息落地 / 分页 / 过期清理 | schema 迁移 |
| RedisService | 辅助缓存 | 临时状态（可选） | 可替换 |
| LocationService | 扩展 | 位置信息（用于上下文） | 可选注入 |
| VehicleStateService | 扩展 | 实时车况（未来支持） | 监听通道 |
| ConfigService | 基础设施 | 端点 / 超时 / 重试策略统一 | 环境隔离 |
| Logger | 基础设施 | 分级日志 + 调试开关 | 生产开关 |
| MarkdownCleaner | 工具 | 清理/裁剪 Markdown 用于 TTS | 多语言规则 |
| ErrorMapper | 工具 | 后端错误码 → 用户友好文案 | 本地化适配 |
4.1.4 服务分层
- 链路图
sequenceDiagram
autonumber
participant UI as UI层
participant MS as MessageService
participant AR as AudioRecorder
participant ASR as VoiceRecognition
participant CLS as TextClassification
participant VCS as VehicleCommandService
participant DLG as ChatSse/WS/HTTP
participant CMD as CommandService
participant HND as VehicleCommandHandler(Host)
participant TTS as TtsService
participant PERS as PersistenceService
UI->>MS: startVoiceInput()
MS->>AR: start()
AR-->>MS: audioChunks / silenceEnd
MS->>AR: stop()
MS->>ASR: recognize(audio)
ASR-->>MS: recognizedText
MS->>CLS: classify(text)
CLS-->>MS: category / scenario
alt 车控指令
MS->>VCS: parseCommands(text)
VCS-->>MS: commands[]
loop each command
MS->>CMD: execute(command)
CMD->>HND: executeCommand(command)
HND-->>CMD: result(success/fail)
CMD-->>MS: executionResult
MS->>TTS: enqueue("执行结果反馈")
MS->>PERS: save(control_feedback)
end
else 普通问答
MS->>DLG: requestStream(text, convId)
DLG-->>MS: streamChunk/ finalMessage
MS->>TTS: enqueue(chunk/segments)
MS->>PERS: save(text / merged)
else 错误/兜底
MS->>TTS: enqueue(提示语)
MS->>PERS: save(system_message)
end
TTS-->>UI: 播放中事件
PERS-->>MS: persist OK
MS-->>UI: 更新消息列表
- 逻辑分层
graph TD
A[UI层] --> B[MessageService]
B --> C1[输入层 AudioRecorder / WakeWord]
B --> C2[语义层 Classification / VehicleCommand]
B --> C3[对话通道层 SSE / WS / HTTP]
B --> C4[执行层 CommandService + Host Handler]
B --> C5[输出层 TtsService]
B --> C6[存储层 PersistenceService]
B --> C7[基础设施 Config / Logger / Redis / Location]
4.1.5 代码示例
- 初始化：
await AiChatCore.init(
config: CoreConfig(
endpoints: Endpoints(
classify: "...",
sse: "...",
ws: "...",
controlParse: "...",
controlExec: "...",
voice: "...",
),
timeouts: Timeouts(connectMs: 8000, receiveMs: 20000),
enablePersistence: true,
persistenceMode: PersistenceMode.hive,
retryPolicy: RetryPolicy(maxAttempts: 2, backoffBaseMs: 400),
),
commandHandler: MyVehicleCommandHandler(),
logger: CustomLogger(),
);
- 统一公共接口：
abstract class AiChatCore {
static Future<void> init({required CoreConfig config, required VehicleCommandHandler commandHandler, Logger? logger});
static MessageService get messageService;
static PersistenceService? get persistence;
}
class MessageService {
Stream<List<Message>> get messageStream;
Future<void> startVoiceInput();
Future<void> stopAndProcessVoiceInput();
Future<void> sendText(String text);
Future<void> abortAnswer();
Future<void> loadHistory({required int page, required int pageSize});
}
4.1.6 编译与分发说明（path 子包 vs 单包）
-
当前结构：插件（ai_chat_assistant）+ 仓库内 path 依赖（packages/ai_chat_core、packages/basic_intl）。
-
下游集成（pubspec）仅需：
ai_chat_assistant: git: url: <repo_url> ref: <branch_or_tag> -
Flutter 构建行为：
- 克隆仓库 → 解析主插件 pubspec → 解析 path 子包 → 汇总全部 Dart 源码。
- Debug：JIT，Release：统一 AOT 编译为一个 snapshot（无包边界差异）。
-
性能与产物差异：将子包“内联”进 lib/ 与保持 path 组织，在编译后无本质差异（tree shaking 后输出等价）。
-
适用场景对比：
目标 保持多包 合并单包 代码隔离 / 复用 优 弱 发布到 pub.dev 需逐包发布 更简单 测试隔离性 优 一般 用户认知成本 稍高 低 -
暂不需发布：保持 path 结构即可；若未来开放生态 → 发布次序：ai_chat_core → basic_intl → ai_chat_assistant。
4.1.7 AAR 与闭源分发说明
| 诉求 | 可行性 | 说明 |
|---|---|---|
| 给“另一个 Flutter App”仅提供预编译 AAR 使用 | 不推荐/不可行 | Flutter 仍需源文件参与整体编译流程 |
| 给纯原生 Android App 内嵌使用 | 可用 flutter build aar |
适用于“原生 App 集成 Flutter 模块”，不是插件分发 |
| Dart 逻辑闭源 | 官方未支持 | 只能转移核心到 native/FFI 或服务端 |
结论：对 Flutter 使用方，直接 Git 依赖即可，无需 AAR。