导入一份 Excel 名单 → 自动识别「手机号」列 → 点击号码跳转系统拨号页并自动填充号码。
- 选择本机
.xlsx文件(手机上是「文件」选择器,无需存储权限) - 多工作表切换,导入时自动挑出最合适的工作表
- 电话号码列自动识别 + 多选:
- 表头关键词(手机 / 电话 / 联系方式 / 手机号码 / phone / mobile / tel …)优先,再结合单元格内容是否为号码格式打分
- 可以同时勾选多列(如「手机号码」+「办公电话」),首页用标签任意增删,卡片右上角显示「已选 N 列」
- 识别不准时同样可手动勾选正确列
- 名单列表:一条记录可展示多个号码(按列名标注手机/固话),点击卡片弹出号码选择器挑一个拨打,点击某个号码则直接拨它
- 拨号时高亮当前行:点号码跳到系统拨号器的那一刻,该行变成浅蓝底 + 主色描边 + 阴影,行首序号变实心蓝、标题旁显示「正在拨打」,并一直保持(不会自动消失),方便确认刚拨的是哪一条;再拨别的行则高亮转移
- 重置时机:点标题栏的刷新按钮 / 菜单里的「刷新列表(清除高亮)」、返回首页后重新进入列表、切换工作表、重新导入表格
- 刷新只清高亮,不影响「已呼叫」绿色标记(那是历史记录,持久保存)
- 座机自动补区号:
- 号码只写了本地座机(如
88886666、51234567)时,拨号会自动加上设置的区号,列表里也会标注「已补区号 021」 - 默认区号 021,首页「固话区号」卡片可从 021 上海 / 010 北京 / 020 广州 / 0755 深圳 / 0571 杭州 / 025 南京 / 027 武汉 / 022 天津 / 023 重庆 / 028 成都 / 0451 哈尔滨 / 0531 济南 中快捷选择,也可手填自定义区号(3-4 位、以 0 开头),选择结果本地持久化
- 已自带区号的号码(
010-88886666、02166668889)、手机号、国际号码完全不受影响,不会重复补
- 号码只写了本地座机(如
- 支持的号码写法:
13800138000、138 0013 8000、138-0013-8000、+86 13800138000、010-88886666、88886666(补区号)、科学计数法1.3800138E+10、13800138000 转 123 - 双机联动播报(实验特性):拨号手机检测到对方接通后,通过局域网通知另一台手机朗读固定开场白,详见下文
- 搜索过滤(姓名 / 号码 / 其他字段)、复制全部号码(同一行多号码用「、」分隔,固话带区号)、已呼叫标记(本地持久化)
- 内置两张示例工作表:「客户名单」(手机号)和「固话名单」(座机,可直观看到补区号效果)
拨号使用系统
tel:Intent:号码会自动填入拨号页,仍需用户点一下拨打键,这样不需要CALL_PHONE权限。
lib/
├─ main.dart 应用入口、主题
├─ models/sheet_data.dart ImportedSheet / PhoneCandidate / CellField
├─ services/
│ ├─ excel_service.dart Excel 解析 + 表头/手机号列识别(含示例数据)
│ ├─ dialer_service.dart 调起系统拨号页
│ ├─ settings_store.dart 固话区号等本地设置
│ ├─ call_log_store.dart 已呼叫号码本地存储
│ ├─ call_state_watcher.dart 无障碍通话状态通道(EventChannel)
│ ├─ lan_link.dart 局域网 UDP 广播通道
│ ├─ live2d_service.dart Live2D 资源释放 + 本地静态服务 + 模型导入
│ ├─ tts_synthesizer.dart 端侧 TTS 合成(sherpa-onnx)+ 振幅包络
│ └─ prompt_link.dart 双机联动编排(接通→广播→朗读→口型)
├─ utils/phone_utils.dart 号码归一化、类型识别(手机/固话/本地座机)、区号补全
├─ pages/
│ ├─ home_page.dart 导入、参数确认(工作表 / 手机号列 / 统计)
│ ├─ record_list_page.dart 名单列表、搜索、拨号
│ └─ prompt_page.dart 双机联动配置(角色 / 开场白 / 日志)
└─ widgets/
├─ record_card.dart 单条记录卡片
└─ live2d_avatar.dart Live2D 数字人组件(WebView + 嘴型驱动)
test/ 18 个用例(号码解析 / Excel 导入 / 列识别 / 界面冒烟)
android/ gradle 工程 + 带 <queries> 的 AndroidManifest
| 组件 | 路径 / 版本 |
|---|---|
| Flutter SDK | D:\Android\flutter\sdk\flutter(3.47.7,未加入 PATH) |
| Android SDK | D:\Android\android-sdk(platform-tools 37.0.1、platforms;android-36、build-tools;36.0.0) |
| JDK | D:\Java\temurin\jdk-21.0.12.1+1(Temurin 21,JAVA_HOME 已设置,与 CI 一致;Android 编译 source/target 仍为 Java 17 字节码) |
环境变量已写入用户级:ANDROID_HOME、ANDROID_SDK_ROOT 指向 SDK,PATH 追加了 platform-tools 和 cmdline-tools\latest\bin;flutter config --android-sdk D:\Android\android-sdk 已设置。flutter doctor 报 [√] Android toolchain (SDK 36.0.0)、许可全部接受。
所有导入/释放/下载的文件统一到一个数据根(lib/services/app_paths.dart,启动时自动迁移旧位置):
| 平台 | 根目录 |
|---|---|
| Windows | exe 同级 userdata\(绿色便携;不可写时回退 %APPDATA%\com.callassistant\call_assistant) |
| Android | 应用外部 files(Android/data/com.callassistant.call_assistant/files) |
子目录:live2d\(WebView 运行时+内置模型,导入模型在 live2d\models\)、audio\opening_audio.wav(开场白)、sherpa\tts\、sherpa\asr\(离线模型,可 adb 推送/直接拷入)。建议把整个程序文件夹放在非同步盘目录(sherpa 模型几百 MB,OneDrive 会同步)。SharedPreferences(设置项)始终在系统 support 目录,不随 userdata 走。
cd d:/test/flutter/call-assistant
flutter pub get
flutter test # 18 个用例:号码解析、Excel 导入、手机号列识别、界面冒烟
flutter analyze
flutter run # 连手机直接调试
flutter build apk --release产物:
build\app\outputs\flutter-apk\app-release.apk(48.9MB,已验证可安装:包名com.callassistant.call_assistant,label「话务助手」,minSdk 24 / targetSdk 36,含tel:的<queries>)build\app\outputs\flutter-apk\app-debug.apk(151.5MB)
本机网络对
github.com/maven.google.com不通,因此android/gradle/wrapper/gradle-wrapper.properties的distributionUrl指向腾讯云镜像,android/settings.gradle.kts与android/build.gradle.kts的仓库列表前置了腾讯云/华为云 Maven 镜像(官方源保留在后面兜底)。换到能直连的网络时可以把镜像删掉。
android/gradle.properties关闭了 Kotlin 增量编译(Windows 下偶发Could not close incremental caches)。
场景:真实手机号外呼时,让对方听到固定的开场白。Android 不允许第三方应用把音频注入蜂窝通话上行,所以这里用两台手机 + 声学耦合的方式实现: 拨号手机检测「已接通」→ 局域网通知播放手机 → 播放手机在拨号手机麦克风旁朗读。
手机A(拨号端) 手机B(播放端,放在A的麦克风旁 5~10cm)
点击号码 → tel: 拨号
│
├─ 无障碍服务读取通话界面
│ 出现 00:05 / 通话中 → 判定已接通
│
└─ UDP 广播 255.255.255.255:47823 ──▶ 收到 answered 指令
{type:answered, script:"开场白"} → flutter_tts 朗读开场白
系统没有给第三方开放「外呼已接通」回调(CALL_STATE_OFFHOOK 在拨号时就触发了),
所以只能读通话界面文案来判断。判据优先级(CallAnswerAccessibilityService):
| 顺序 | 条件 | 结论 |
|---|---|---|
| 1 | 出现「通话结束 / 已挂断」 | 通话结束 |
| 2 | 出现「正在拨号 / 正在呼叫 / 呼叫中 / 已拨出」 | 未接通(忽略后续) |
| 3 | 出现「通话中 / 已接通 / 正在通话 / 通话时长」 | 已接通 |
| 4 | 计时器数值在变化(两次采样不同) | 已接通 |
两个关键坑:
- 拨号界面里也有时间(MIUI 拨号盘顶部是时钟,状态栏也是
21:30), 只靠「出现数字:数字」会把刚拨出去还没接通就判成接通。 → 现在要求计时器确实在走动(两次采样值不同)才算通话计时器。 - 呼叫中界面已经有红色挂断键(和通话中界面一样), → 所以「挂断」不能作为接通判据,只能作为辅助信息。
实测:拨出未接通的号码(呼叫中界面顶部显示「正在拨号」)不再误报; 接通后界面会出现「已接通」或开始走动的通话计时器 → 正常触发播报。
联动页快捷条上「立即播报」旁边有 「停止」:
- 停掉本机正在播放的音频/TTS 与嘴型动画
- 同时通过局域网广播
stop指令,让播放端也立刻停下(否则只停了拨号端,播放端还在念) - 播放端收到
stop后执行stopSpeaking()并记录「收到停止播报指令」 - 另外播放端收到新的播报指令时会先停掉正在播的内容再播新的,避免叠音
表格可能有几百行,所以名单页默认用紧凑模式:
① 张伟 📞
手机号码 13800138000 办公电话 010-88886666
部门: 销售一部 · 备注: 首次咨询
- 每行压到约 60 高(详细模式约 120),一屏能看到的行数多一倍以上
- 序号变成小圆点,号码横排显示并可直接点击拨打,右侧一个圆形拨号按钮
- 第二行是字段摘要(部门/备注等,最多两条,自动跳过与序号重复的字段)
- 标题栏有「密度切换」按钮,可在紧凑 / 详细之间切换,选择会被记住
- 列表用
ListView.builder懒加载,几百行也能流畅滚动
全局提示不再用底部 SnackBar,改为居中浮层(lib/widgets/app_toast.dart):
- 居中显示,不遮挡底部操作区(悬浮玻璃按钮所在的位置)
- 主题色渐变(
#4A82FF → #2F6BFF)+ 图标 + 白字;错误提示用红色系,一眼可辨 - 自动淡入淡出 + 轻微缩放,不打断操作(
IgnorePointer,点击可以穿透) - 生命周期用单个
AnimationController走完「入场 → 停留 → 退场」,不用 Timer(否则 widget 测试的pumpAndSettle会一直等下去)
名单列表页:双列多行
┌────────────┐ ┌────────────┐
│ ① 中国移动客服 │ │ ② 中国联通客服 │
│ 手机号码 │ │ 手机号码 │ ← 窄卡里号码竖排(标签在上)
│ 10086 │ │ 10010 │
│ 办公电话 │ │ 办公电话 │
│ 010-8888… │ │ 010-8888… │
│ 部门: 客服热线│ │ 部门: 客服热线│
└────────────┘ └────────────┘
- 紧凑模式改成两列网格,左右留白收紧让每列更宽(号码不易换行),卡片高度只够「姓名 + 号码 + 拨打情况」(84),一屏能看 12+ 张卡
- 拨号图标已移除(省下的空间全给号码,双列 15px、单列 17px)
- 号码与列名同一行(手机号码 10086),长号码用 FittedBox 自动缩放,不换行不截断
- 已标记的拨打情况显示为绿色小标签
- 长按卡片可弹出该行完整信息(弹窗整体下沉,从屏幕更下方升起):所有号码(可直接点拨)+ 全部字段 + 拨打情况设置(短按仍是拨号,单列/双列都支持)
拨打情况(表格末尾新增一列)
- 导入表格时自动在末尾追加「拨打情况」列;长按卡片的弹窗里可以一键标记:拨打成功 / 未接听 / 已关机 / 自定义填写(弹输入框自己写,如「客户说下周一再联系」),也能清空
- 标记结果写回该行的「拨打情况」列,并在卡片上显示为绿色小标签
- 同时按「表格名 + 行号」存到本地,下次进同名表格会自动带回来
- 导出为 xlsx:列表页右上角菜单 →「导出为 xlsx(含拨打情况)」,把表头 + 全部数据行(拨打情况在最后一列并已填充)写成 xlsx
- 直接通过 MediaStore 存到系统「下载」目录(不需要任何存储权限,也不会被系统保存对话框卡住),提示里会给出文件路径
- 极端情况下退回系统「另存为」对话框
- 清空所有拨打情况:同一菜单里,二次确认后清空当前表格全部行(含本地缓存)
- 导出的文件再导入时不会重复追加「拨打情况」列(会复用已有同名列)
- 标题栏在排版(密度)按钮左边新增「双机联动播报」快捷跳转;切到详细模式仍是单列大卡片
拨号页(首页)
┌───────────────┬───────────────┐
│ 工作表 │ 统计 │ ← 两卡顶部对齐
├───────────────┴───────────────┤
│ 电话号码列(可多选) │ ← 号码列在区号上面
├───────────────────────────────┤
│ 固话区号(chip 多列排开) │
└───────────────────────────────┘
┌───────────────────────────┐
│ [导入其他表格] │ [开始拨号] │ ← 悬浮液态玻璃条
└───────────────────────────┘
- 「工作表」与「统计」两张卡顶部对齐且等高(IntrinsicHeight);点左边卡片可弹出「表格信息」看完整文件名、数据行、列数、表头位置等(标题被截断时也能看全)
- 「电话号码列」放在「固话区号」上面
- 「导入其他表格」与「开始拨号」做成悬浮液态玻璃条(背景模糊 + 半透明渐变 + 高光描边 + 投影),始终可点、不随内容滚走
表格导入成功率提升
- 支持 .xlsx / .xls / .csv / .txt;csv、txt 直接按逗号或制表符分隔解析(支持双引号包裹与转义)
- 解析失败时会把底层原因带出来(不再只给一句「无法解析」),并提示如何另存为 xlsx
- 名单卡片的字段区不展示「序号」项(长按详情里仍能看到完整字段,含序号)
- 号码识别新增服务号类型:5~6 位的公开服务电话(
10086/10010/10000/12345)。服务号与「编号 10001」太像,所以单独判断:只有当该列表头命中电话关键词、且列里还有标准格式号码时,才把服务号计入 —— 否则编号列会被误当成号码列
内置示例名单
前 3 行是三大运营商的客服热线(10086 / 10010 / 10000)——都是公开服务电话,接通后是语音提示,既能跑通「接通 → 播报」全链路,也不会打扰到真人。
- 按文件后缀识别模型:
*.model3.json(大小写不敏感,Hiyori.model3.json与model3.json都认);后缀被改过时再按内容兜底(json 含FileReferences+Moc即认为是模型描述文件) - 「导入模型包(zip)」:选 zip 压缩包,自动找到里面的模型描述文件并连同贴图/动作/表情一起释放
- 「从文件夹导入模型」:直接选一个文件夹,递归查找模型描述文件,把模型所在目录整体复制到应用目录(适合已经解压好的模型)
- 扫描会跟随符号链接、最多 8 层,并有一次性递归遍历兜底
- 失败时给出具体原因(目录读不到 / 有 json 但不是模型描述文件 / 确实没有),不再一律报「没有找到 .model3.json」
- Android 11+ 分区存储:需要「所有文件访问权限」(MANAGE_EXTERNAL_STORAGE)。没授权时点击「导入文件夹」会直接跳转到系统授权页,开启后再导入即可
- 目录选择走系统 SAF(ACTION_OPEN_DOCUMENT_TREE)并在原生侧把 documentId 解析成真实路径(MIUI/HyperOS 的 oot: 卷名也做了兼容),不依赖各 ROM 行为不一致的文件选择器
- 找不到模型时会说明原因(目录读不到 / 有 json 但不是模型描述文件 / 确实没有)
Windows 的 WebView2 默认是白色不透明背景,会导致:
- 模型周围出现一圈白/灰块
- 浮窗贴到屏幕左/右边缘时,超出部分露出灰白条
处理方式(live2d_avatar.dart 的 _bootstrapWindows):
await controller.setBackgroundColor(const Color(0x00000000));- 只能传 alpha = 0 的全透明,传半透明会被 WebView2 当成不透明
- 页面本身也必须是透明背景(
assets/live2d/index.html里html, body { background: transparent; }) - Android 侧本来就通过
webview_flutter设了同样的透明背景,两端表现一致
「切换模型」列表里:
- 内置模型(Haru / Hiyori / Mao / Mark / Natori / Rice / Wanko)不可移除 —— 没有删除按钮
- 用户自己导入的模型(路径以
models/开头的)可以移除:点右侧的 🗑️ → 二次确认 → 连目录一起删除 - 移除的如果是当前正在使用的模型,会自动切回默认模型(Hiyori)
区分依据:内置模型放在资源根目录(hiyori/、haru/ …),用户导入的统一放在 models/ 下。
- 长按详情弹窗(名单页):高度随内容自适应,内容少时弹窗就矮,不再在上方留大片空白;字段改成双列排布(标签 54px + 值),并去掉了与高亮 chip 重复的「当前拨打情况」行
- 确认弹窗统一用
lib/widgets/confirm_dialog.dart:- 取消与确认按钮固定在同一行、宽度一致(
Row+Expanded),不会被长文案挤成两行 - 确认按钮实心主题色,危险操作(清空 / 移除模型)用红色,一眼能找到
- 取消按钮为描边样式,不抢主操作的视觉权重
- 标题可带图标(清空=扫帚、移除=垃圾桶)
- 取消与确认按钮固定在同一行、宽度一致(
「播报」标签页 → 开场白音频卡片 →「把这段音频转成文本」→ 识别结果弹窗(可直接改)→「填入」回写到开场白文本框。
完全离线:用 sherpa-onnx 的离线识别器(和端侧合成同一套技术栈),录音不会上传。
支持全格式:新增 Android 原生解码器(AudioDecoder.kt,MediaExtractor + MediaCodec),
mp3 / m4a / aac / ogg / wav / amr 等常见格式都能读,统一转成 16kHz 单声道 WAV 再送识别器。
解码结果写成文件而不是走 MethodChannel,避免长录音超 Binder 事务 1MB 限制。
模型(在「语音识别模型」卡片导入,.tar.bz2 格式,导入后自动识别,无需手动解压):
| 模型 | 体积 | 语言 | 说明 | 下载 |
|---|---|---|---|---|
sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17 |
155 MB | 中/英/日/韩/粤(自动检测) | 推荐,自带标点 | 下载 |
sherpa-onnx-paraformer-zh-small-2024-03-09 |
74 MB | 中文 | 更轻,速度快 | 下载 |
| zipformer(transducer 族) | 视模型 | 中/英 | encoder + decoder + joiner 三件套 | 全部模型 |
| whisper | 视模型 | 99 种 | 语种最全,但慢且大 | 全部模型 |
上面两个直链是
asr-modelsrelease 里的固定资源;如果点了 404,去「全部模型」页搜同名文件即可。
模型架构自适应(AsrArch)
按模型目录里的文件特征判定,不再只看目录名(之前只支持 SenseVoice / Paraformer):
| 目录特征 | 判定的架构 | 用的 config |
|---|---|---|
encoder* + decoder* + joiner* |
Transducer(zipformer 等) | OfflineTransducerModelConfig |
*encoder* + *decoder* 且目录名含 whisper |
Whisper | OfflineWhisperModelConfig |
目录名含 sense |
SenseVoice | OfflineSenseVoiceModelConfig |
其余(单文件 + tokens.txt) |
Paraformer | OfflineParaformerModelConfig |
model*.onnx,从文件上分不开,只能看目录名 ——
所以解压后不要改目录名(sherpa-onnx-sense-voice-... / -paraformer-...)。
不设 modelType:sherpa 按「填了哪个 config」自行判断架构,手写字符串反而容易错。
- 模型目录:
/storage/emulated/0/Android/data/<包名>/files/sherpa-asr/,也可直接用 adb 推入 - 识别开了逆文本正规化:数字会输出成「10086」而不是「一万零八十六」
- 开了标点,输出自带逗号句号
PC 端定位为播放端:替代第二台手机,接收手机拨号端发来的播报指令并朗读(可带 Live2D 数字人)。
平台差异(由 lib/services/platform_bridge.dart 统一收拢)
| 能力 | Android | 桌面端 |
|---|---|---|
| 拨号跳转(系统拨号页) | ✅ | ❌ 改为复制号码 |
| 「拨号端」角色(检测接通) | ✅ | ❌ 隐藏,PC 只当播放端 |
| 无障碍通话检测 | ✅ | ❌ 不支持 |
| 局域网双机联动 | ✅ | ✅ PC 与手机同 Wi-Fi 即可 |
| 立即播报 | 广播给播放端 | 本机播报 |
| Live2D 数字人 | ✅ | ✅(WebView2) |
| 端侧 TTS / ASR | ✅ | ✅(ASR 的音频解码暂仅 Android) |
| 保存导出文件 | 系统「下载」目录 | 系统保存对话框 |
宽屏适配:桌面端内容区限宽 820px 居中(DesktopBody),但 AppBar 仍然通栏,更像桌面应用;两侧用页面背景色铺满,不会露出黑块。
桌面端的三个坑(都已处理)
| 坑 | 现象 | 处理 |
|---|---|---|
flutter_tts 在 Windows 上调 SAPI |
机器没装语音引擎时原生层崩溃(整个 App 闪退,try/catch 拦不住) | 桌面端完全禁用系统 TTS,统一走端侧合成(导入 TTS 模型即可) |
缺 webview_flutter_windows |
数字人一片空白,报 WebViewPlatform.instance != null |
pubspec 显式声明 webview_flutter_windows,并确认它出现在 windows/flutter/generated_plugins.cmake 里 |
webview_flutter_windows 1.x 不是 webview_flutter 的平台实现 |
它是独立的 WebView2 组件(Webview / WebviewController),WebViewController 那套 API 在 Windows 上完全不可用 |
数字人组件按平台分两套实现:Android 用 webview_flutter,Windows 用 webview_flutter_windows 的 loadUrl / executeScript / loadingState |
| 缺 WebView2 Runtime | 数字人不加载(浏览器进程起不来,不会触发任何错误回调,只会一直白屏) | 安装 WebView2 Runtime;App 内也有「下载 WebView2 Runtime」按钮 |
构建 Windows
# 一次性准备:开启「开发者模式」(Flutter Windows 插件需要创建符号链接)
# 设置 → 系统 → 开发者选项 → 开发人员模式
# 或用管理员 PowerShell:
reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v AllowDevelopmentWithoutDevLicense /d 1
flutter pub get
flutter build windows --release # 产物在 build/windows/x64/runner/Release/打包成发行 zip(tool/make_windows_release.ps1):
powershell -ExecutionPolicy Bypass -File tool\make_windows_release.ps1
powershell -ExecutionPolicy Bypass -File tool\make_windows_release.ps1 -Version 1.2.1产物 build/windows/call-assistant-<版本>-windows-x64.zip,解压后只有一层:
call-assistant-windows-x64\call_assistant.exe
zip 内的目录名固定不带版本(用户解压后得到一个稳定名字),版本号只出现在 zip 文件名上。
GitHub Actions 用的是同一个脚本(.github/workflows/release.yml 的 release-windows),
只是多传一个 -OutDir build,让 zip 落在 build/ 下与上传路径匹配:
powershell -ExecutionPolicy Bypass -File tool/make_windows_release.ps1 -Version "$env:APP_VERSION" -OutDir build三点说明:
- Flutter 的产物在
build\windows\x64\runner\Release\下,直接压缩那一层会把 exe 和十几个 dll 平铺在 zip 根目录(解压后文件散一地)。脚本先把内容搬到staging\<发行目录名>\再压缩, 保证 zip 内第一层就是发行目录。 - 打包时排除
userdata/:那是运行时生成的(用户数据、导入的模型、日志), 打进发行包既占体积又可能带上私人数据 —— 实测这一项就有 82MB,排除后 zip 只有约 37MB。 - 压缩优先用 7z(资源里模型文件名带中文,
Compress-Archive在某些环境下会乱码), 没有 7z 时退回Compress-Archive。
⚠️ 改这个脚本时注意:PowerShell 5.1 读取「无 BOM 的 UTF-8」会按系统 ANSI 解析, 中文注释被误解码成乱码后会把引号/括号吞掉,报出莫名其妙的Missing closing '}'/The string is missing the terminator。 所以这些.ps1都存为 UTF-8 with BOM。
桌面端的内置资源不再复制一份
assets/live2d/ 约 20MB(7 个内置模型)。Android 上 asset 在 apk 里、没有文件路径,
必须释放成文件;但桌面端的 asset 本来就是实体文件,放在可执行文件旁边:
| 平台 | app 内 asset 路径 |
|---|---|
| Windows / Linux | <exe 目录>/data/flutter_assets/assets/live2d |
| macOS | Contents/Frameworks/App.framework/.../Resources/flutter_assets/assets/live2d |
所以桌面端直接按路径读取,不再复制到 userdata(Live2dService.builtInLive2dDir),
省掉一整份重复占用。userdata 下的 live2d/ 只用来放用户导入的模型(models/)。
配套的改动:
- 本地 HTTP 服务读文件时会回退到 app 自带目录(
_handle) - 模型列表会同时扫 userdata 与 app 自带目录(
listModels),并对同名去重 ⚠️ Windows 原生渲染后端也要走同一套规则:它不走 HTTP,而是把模型目录路径 直接交给插件按文件加载(贴图 / moc3 都是插件自己读)。所以目录必须经过Live2dService.resolveModelDir()解析(先 userdata,再 app 自带资源)—— v1.2.4 就是漏了这一处,表现是「Windows 加载不到默认模型」(v1.2.5 修复)- 旧版本已经复制过的那份,首次启动会自动回收(只保留
models/,见_removeCopiedBuiltInAssets)
没有管理员权限时无法创建符号链接,构建会提示
Building with plugins requires symlink support。
构建 Windows(两个一次性前置条件)
- 开启「开发者模式」(Flutter 插件构建需要创建符号链接)
- 设置 → 系统 → 开发者选项 → 开发人员模式
- 或用管理员 PowerShell 执行:
reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v AllowDevelopmentWithoutDevLicense /d 1
- 安装 nuget.exe 并放进 PATH(
flutter_tts的 Windows 实现要用它拉取 Speech API)curl.exe -L -o d:\tools\nuget.exe https://dist.nuget.org/win-x86-commandline/latest/nuget.exe $env:PATH="d:\tools;$env:PATH" # 每次构建前确保它在 PATH 里
然后:
flutter pub get
flutter build windows --release # 产物在 build/windows/x64/runner/Release/
若报
file cannot create directory: C:/Program Files/...,说明上次构建把安装前缀缓存成了 Program Files, 删掉build/windows目录重新构建即可。
桌面端不再用浮窗展示数字人,改成左右分栏:
┌──────────────┬────────────────────────────────┐
│ 数字人 │ 主操作界面 │
│ ┌────────┐ │ ┌──────────────────────────┐ │
│ │ Live2D │ │ │ 播放端 / 立即播报 / 停止 │ │
│ └────────┘ │ │ │ │
│ 提词气泡 │ │ 本机角色 / 单机自测 │ │
│ 上一步 下一步 │ │ 名单 / 数字人 / 日志 │ │
└──────────────┴────────────────────────────────┘
为什么改:Windows 的 WebView2 是原生控件(hybrid composition),浮在 Flutter 内容之上时会出现一串问题 —— 透明背景要等控件创建后设置才生效、resize 后背景色会被重置、Flutter 的裁剪对原生控件无效导致贴边露灰条。改成固定分栏后,数字人就是普通布局的一部分,行为稳定。
-
左栏与右栏各占一半(两边都用
Expanded均分,只有中间 1px 分隔线;窗口怎么缩放都严格对半) -
中间是 Live2D 角色(白底卡片内渲染,没有裁剪/透明问题)
-
下面是提词气泡(客户信息 + 话术提词,最大高度为窗口高度的 40%)
-
再下面是「上一步 / 下一步」和**「切换模型」快捷入口**(与手机端共用 ModelPickerSheet)
-
手机端保持原来的浮窗(可拖动、可贴边收起)
实现上把「数字人 + 提词气泡」抽成 lib/widgets/avatar_stage.dart(AvatarStage / AvatarBubble),手机浮窗和桌面分栏共用一份渲染逻辑。
Windows 数字人的几个坑(都已处理)
| 坑 | 现象 | 处理 |
|---|---|---|
webview_flutter_windows 1.x 不是 webview_flutter 的平台实现 |
它是独立的 WebView2 组件(Webview / WebviewController),WebViewController 那套 API 在 Windows 上完全不可用 |
数字人组件按平台分两套实现:Android 用 webview_flutter,Windows 用 loadUrl / executeScript / loadingState |
setBackgroundColor 调用时机 |
原生侧有 IsValid() 检查,控件没建好时静默失败 |
放到 loadUrl 之后调用,并在导航完成时兜底重设 |
| resize 后背景色被重置 | 展开→贴边后背景又变回默认灰色 | 用 LayoutBuilder 感知宽度变化,变了就重设一次透明 |
dispose 没释放原生控件 |
关掉数字人后还残留一块擦不掉的灰色矩形 | dispose 里显式 controller.dispose() |
| 背景色只能全透明 | 插件把任何 alpha>0 的值都当成不透明 | 传 Color(0x00000000),页面侧 html, body { background: transparent } |
开场白音频始终是同一个文件(应用项目目录 documents/opening_audio.wav):
- 端侧合成(sherpa-onnx)直接写到这个文件,每次生成覆盖上一次的
- 导入外部音频(mp3 / wav / m4a / aac / ogg)时复制过去,同样是覆盖
- 麦克风录制:录完也拷到这里(见下方「用麦克风录制开场白」)
- 清除时连同
.env.json(嘴型包络)一起删掉 - 旧版本留下的
opening_tts_<时间戳>.wav会在下次合成时自动清理,路径也会在启动时迁移到固定文件
用麦克风录制开场白
卡片上的「用麦克风录制」→ 弹窗里「开始录音」(显示计时)→「停止并保存」:
- 录 16kHz 单声道 wav:播放(audioplayers)和离线识别(sherpa)都能直接读
- 录完拷到上面那个固定文件(与「导入音频」同一条落盘链路),旧的被覆盖
- 首次使用会请求
RECORD_AUDIO权限;拒绝时弹窗直接提示去系统设置开启 - 想确认效果就点「本机试听」
依赖 record 7.1.2(Android / Windows / macOS / Linux 都有实现)。
好处:不会越攒越多临时文件,偏好设置里存的路径永远是同一个,也方便用户自己从应用目录取走。
Windows 的 Flutter 默认用 Impeller 渲染器,在部分显卡驱动上文字(尤其中文)渲染发虚。
修复方式是在引擎层直接关掉 Impeller(windows/runner/main.cpp):
flutter::DartProject project(L"data");
// Impeller 在部分 Windows 显卡驱动上文字渲染发虚,改用 Skia
project.set_impeller_switch(flutter::ImpellerSwitch::Disabled);- 写进代码里,不需要每次构建都加
--no-enable-impeller(release 构建 tool 也不支持这个参数) - Android / iOS 不受影响(Impeller 在移动端表现良好)
- 代价:Skia 在部分场景下性能略低于 Impeller,桌面端够用
path_provider 在 Windows 上不支持 getExternalStorageDirectory()(抛 UnimplementedError),getApplicationDocumentsDirectory() 同样不支持 —— 只有 getApplicationSupportDirectory() 能用。原来的写法是 external ?? documents,因为异常在 ?? 之前就抛出,两个都不支持时整个函数静默失败,表现为数字人打不开、「切换模型」点了没反应。
修法:getExternalStorageDirectory() 失败时回退到 getApplicationSupportDirectory()(%APPDATA%\<company>\<app>\live2d),并补了日志。
原生后端依赖 flutter_live2d 1.0.2。这个插件开箱即用时模型能加载但画面永远空白,排查后确认是两个上游 bug(都已通过 tool/patch_live2d_plugin.dart 本地修补):
// 插件原始代码
nativeCreateView(JNIEnv*, jclass) {
FrameworkRetain(); // ← 在 Android 主线程调用,无 EGL context
Live2DView* view = new Live2DView();
return ...;
}CubismFramework::Initialize() 内部会 CreateRenderer → 生成 OpenGL shader program。没有 current context 时 shader 全部编译失败,program 恒为 0,之后每帧 glUniform* / glDrawElements 都报 GL_INVALID_OPERATION (0x502)。
修复:把初始化延迟到 nativeOnSurfaceCreated() —— 它在 render hub 线程执行,已 eglMakeCurrent,是唯一安全的时机。同时在 Live2DView 上加 frameworkRetained 标志,保证 FrameworkRetain/FrameworkRelease 配对。
Cubism 通过下面的方式读 shader:
Live2DPal::LoadFileAsBytes("FrameworkShaders/VertShaderSrc.vert") // → AAssetManager_open也就是从 APK assets 里找 FrameworkShaders/。但插件的 build.gradle.kts 只配了 java.srcDirs,shader 文件一直躺在 cpp/CubismFramework/Rendering/OpenGL/Shaders/StandardES/ 里,从未进入 assets → shader 加载返回 null → program 同样为 0。
修复:把 StandardES/*.vert / *.frag(36 个)复制到 android/src/main/assets/FrameworkShaders/。
关闭时 nativeDestroyView 会 FrameworkRelease() → refCount 归零 → CubismFramework::Dispose()。重新打开时:
nativeOnSurfaceCreated可能还没被调用(新 SurfaceTexture 异步就绪),Framework 仍是未初始化状态 →CreateRenderer拿不到 shader program- 更隐蔽的是:插件 Kotlin 侧的
queueEvent有if (target.eglSurface != EGL_NO_SURFACE)判断,surface 没就绪时会把 loadModel 事件静默丢弃 → 对应的 Dart Future 永远不返回(表现为「模型一直不加载」且没有任何报错)
修复(两处):
nativeLoadModel里补一次 Framework 初始化(此时已在 render hub 线程且eglMakeCurrent过):
if (!view->frameworkRetained) {
FrameworkRetain();
view->frameworkRetained = true;
}- Dart 侧给每次
loadModel加 2 秒超时 + 8 次重试(400ms 间隔),避免被插件静默丢弃时永久挂起
// 插件原始代码
if (view->width > view->height)
model->GetModelMatrix()->SetHeight(2.0f); // 横容器:高度填满 ✓
else
model->GetModelMatrix()->SetWidth(2.0f); // 竖容器:宽度填满 → 高度溢出 ✗竖容器里按宽度填满时,瘦高模型(如 Natori,宽高比约 0.49)的高度会达到视口高度的 1.4 倍以上 —— 头和脚都被裁掉,只剩半身。
修复:统一改成「按高度填满」:
const float aspect = (float)view->height / (float)view->width;
const float targetH = 2.0f * (aspect > 1.0f ? aspect : 1.0f);
model->GetModelMatrix()->SetHeight(targetH);实测:fit view=795x1104 aspect=1.389 targetH=2.777 → 模型完整显示且高度最大化。
Live2D 的裁剪空间是正方形 [-1,1]²,而视口(手机屏)是长方形。NDC → 屏幕的映射
本身就是各向异性的,所以要让模型在屏幕上不变形,必须满足:
P_x * M_x * W == P_y * M_y * H (W/H = 视口像素宽高比)
| P_x | P_y | 模型矩阵 | 结果 | |
|---|---|---|---|---|
| 正确 | H/W(竖容器) |
1 | 等比 | 屏幕等比 ✓ |
| 错误 | 1 | 1 | 等比 | 条件退化成 W == H,竖屏不成立 → 纵向拉长 ✗ |
真正的坑在 CubismMatrix44::Scale():它是赋值语义(_tr[0] = x),不是累乘。
贴边缩放那行 mvp.Scale(s, s) 会把投影里 x 方向的补偿(H/W ≈ 1.73)直接覆盖成 1,
补偿一失效模型立刻被拉长。必须用 mvp.ScaleRelative(s, s)(累乘)。
另外投影要每帧重设(放在 ApplyViewportFit 里),不能只放在 nativeOnSurfaceChanged ——
surface 尺寸没变时那个回调根本不会来,投影会一直是未初始化的值。
还有两个配套的坑:
CubismModelMatrix::SetHeight()内部是Scale()(相对累乘)→ 每帧调用会让缩放 指数级累积(模型缩成一条腿),所以每帧要先LoadIdentity()再设缩放SetCenterPosition()移动的是 canvas 中心,而本体边界给的是本体中心 (归一化到 canvas 尺寸),两者相差 canvas 的一半 —— 补偿里必须减掉0.5, 否则模型整体偏移半屏
✅ 原生后端的「贴边缩成小人」已启用(NativeAvatarRenderer.setCompact 下发
__compact_enable__ / __compact_half_w__ / __compact_h_ratio__)。C++ 侧
ApplyViewportFit 在已算好的 canvas 适配之上再叠一层
ScaleRelative(k,k) + TranslateRelative(...):把整个 canvas 缩到「窄条」对应的
NDC 范围并贴到视图右上角,Flutter 侧裁剪露出的正是右上角 → 看到完整的缩小版模型。
关键做法(为什么这样稳):
- 不重算绝对变换,只在可用的展开变换上叠缩放+平移 —— 各向异性补偿(投影 px/py)
与「累乘语义」极易算错,直接在
Scale()(赋值语义)上重推会跑偏。 - 平移作用于模型空间,需除回投影的 px/py(投影在模型矩阵之后乘)。
- 缩放用
ScaleRelative(累乘)而非Scale(赋值),且每帧LoadIdentity重算, 不会逐帧累积。 - 参数非法(未收到 / 窄条几乎占满 = 其实没缩小)时自动退回普通适配,模型不会消失。
贴边按 canvas(而非角色本体)缩放,和 WebView 侧 compact fit 同语义 (
baseW/baseH就是 canvas 尺寸):角色周围会留白,但保证完整可见、不变形。 WebView 侧仍可用model.getLocalBounds()拿本体精确范围。
⚠️ 上游补丁脚本有两个 marker 冲突坑(曾导致补丁被静默跳过):
6.5的 marker「有「角色本体」边界」与结构体字段注释里的同名子串冲突, 会让本体分支被误判成「已打过」而跳过;- 新加的
compactEnable结构体字段,其 marker 也不能用裸词compactEnable(ApplyViewportFit/setParameter也引用了它)→ 改用compactEnable = false;。 现在展开态仍走 canvas 适配(本体展开分支未在真机验证,暂不启用)。
各模型的嘴型参数名不统一(model3.json 的 Groups.LipSync 声明):
| 模型 | LipSync 参数 |
|---|---|
| hiyori / haru / natori | ParamMouthOpenY |
| mao | ParamA |
| wanko | PARAM_MOUTH_OPEN_Y(全大写) |
| mark / rice | 无 LipSync 组(模型本身没有嘴部参数) |
原来两端都硬编码 ParamMouthOpenY,所以只有前 3 个模型能动。
修复:
- WebView:从
model.internalModel.settings.groups里找LipSync组,用它的 ids - 原生:
GetParameterIndex(id) < 0时回退到Live2DModel::_lipSyncIds(Cubism 的GetLipSyncParameterId)
实测日志:lipSync ids = ["ParamA"](mao)。
Live2DModel::Update() 的开头会 _model->LoadParameters() —— 把所有参数重置回默认值:
void Live2DModel::Update() {
_model->LoadParameters(); // ← 嘴型被清成 0
_motionManager->UpdateMotion(...); // ← motion 还会再覆盖一遍
...
_model->Update(); // ← 这里才把参数写进顶点
}而 nativeSetParameter 原来调的是 SetParameterValue,它只在 render loop 的 drain events 阶段(Update() 之前)设值 → 下一帧开头就被重置,嘴型永远是 0。
WebView 侧没这个问题,因为它在 afterMotionUpdate 事件 + ticker 里应用嘴型(动作更新之后)。
修复:新增 Live2DModel::SetExternalParameter(),把值缓存到 _externalParams,在 Update() 里 _model->Update() 之前重新应用:
for (auto it = _externalParams.Begin(); it != _externalParams.End(); ++it)
SetParameterValue(it->First.GetRawString(), it->Second);
_model->Update();修完实测日志:mouth externalParams=1 applied=0.176 → 0.624 → 0.322 → 0.585(值在真实变化)。
| 检查项 | 结果 |
|---|---|
| 模型加载 | LoadAssets done, IsLoaded=1 ✓ |
| 纹理上传 | tex[0] id=1 1024x1024 texture_00.png ✓ |
| MVP 矩阵 | mvp=[1.57 0 0 0 | 0 0 0 1] ✓ |
| 渲染循环 | 每帧 nativeOnDrawFrame + eglSwapBuffers ✓ |
| 投影/视口 | viewSize=1155x907,比例正确 ✓ |
唯一异常就是 glErr:修好后从 0x501 → 0x502 变成恒为 0x0,模型立即正常显示。
flutter pub get
dart run tool/patch_live2d_plugin.dart # 幂等,重复执行安全
flutter build apk --release- 脚本从
.dart_tool/package_config.json定位插件目录,找不到就回退扫 pub cache - 每一步都有幂等标记,已打过补丁会输出「已打过补丁」并跳过
- 每次
flutter pub get重建 pub cache 后需要重新执行一次 - CI 的
ci/release-android两个 job 已在pub get之后自动执行
MaterialApp.builder 返回的内容位于 Navigator 之外,所以桌面分栏里的控件:
showModalBottomSheet会抛「找不到 Navigator」→ 点了没反应Overlay.maybeOf(context)返回 null → Toast 静默不显示
修法:新增 lib/services/app_navigator.dart,用 GlobalKey<NavigatorState> 拿到全局 Navigator,弹窗和 Toast 都改走 resolveNavigator(context) / resolveOverlay(context)(优先用 context 上的,回退到全局 key)。
浮窗由「角色盒 + 右侧操作栏 + 下方话术框」组成,尺寸全部由 FloatingAvatarHost 的静态方法推导:
| 参数 | 值 | 说明 |
|---|---|---|
avatarHeight(screenWidth) |
screenWidth * 0.58(clamp 260~420) |
角色盒高度先定,竖屏下约 401 |
avatarAspect |
0.60 |
角色盒宽 / 高(从 0.72 收窄,减少右侧空白) |
avatarBoxWidth |
avatarHeight * 0.60 |
约 241 |
groupWidth |
avatarBoxWidth + 84 + 8 |
约 333(整组宽度) |
barWidth |
ArcActionBar.barWidth = 84 |
左侧弧形操作栏 |
| 图标 / 点击区 | 27 / 46 |
图标加大,方便点 |
barGap |
8 |
角色盒与操作栏间距 |
| 话术框间距 | 6 |
与角色盒之间 |
贴边(紧凑)模式的实现
贴边时浮窗只剩一条窄边(112px),但不能重建 / resize 渲染视图 —— Android 平台视图 每次 resize 都要重建 surface,动画中做必然掉帧;重建则更慢(要重新加载模型)。
所以采用「同一个视图 + 视图内缩放 + 裁剪」:
| 环节 | 做法 |
|---|---|
| 视图尺寸 | 始终是展开尺寸(OverflowBox + ClipRect 裁剪),永不 resize |
| 模型缩小 | 页面侧 avatar.setCompact(on, side, w, h) → fit() 按窄条尺寸算 scale,把模型缩到 112×152 并靠到视图右上角 |
| 露出哪边 | 两种后端都露右上角(Alignment.topRight)—— 模型都被缩到窄条并贴右上角 |
| 贴边时 | 话术框与操作栏被裁掉,只留模型 |
| 恢复展开 | 直接点模型即可恢复(不需要额外的展开按钮) |
| 两种后端贴边时都是把 canvas 缩到窄条并贴右上角(原生侧的实现见上面「贴边缩成小人」那段): |
- WebView:页面内
avatar.setCompact()→fit()按窄条尺寸算 scale, 模型缩到 112×152 并贴到视图右上角 → 看到缩小版的完整模型 (页面里能用model.getLocalBounds()拿到角色本体的精确范围,位置算得准) - 原生:
__compact_*__→ C++ApplyViewportFit在 canvas 适配上叠ScaleRelative + TranslateRelative,把整个 canvas 缩到窄条并贴右上角 → 同样看到缩小版的完整模型(按 canvas 缩放,周围留白,与 WebView 侧同语义; Cubism Native 没有getLocalBounds()的等价 API)
点模型能恢复的前提:原生后端的 Live2DView 是平台视图,默认
(hitTestBehavior: opaque)会独吞所有触摸,外层 Flutter 的
GestureDetector 收不到事件。补丁里把它改成 transparent,触摸才能传到
Flutter;WebView 侧则靠 CSS pointer-events: none 穿透。
拖动的跟手度:AnimatedPositioned 在拖动过程中会不断重启一个 240ms 的位移动画,
浮窗永远在追手指 → 看着「不灵敏」。现在拖动中禁用位置动画(Duration.zero),
松手后才恢复动画。
model.y = 0)而不是
贴底 —— 露出的是视图的右上角,贴底就只露出空白。
WebView 的触摸穿透
Android 的 WebView 是混合合成的原生控件,会吃掉所有触摸事件,导致外层 Flutter 的
GestureDetector(拖动数字人)完全收不到手势。解决:在 index.html 的 <style> 里加
html, body { ... pointer-events: none; }让触摸穿透回 Flutter(模型交互本来就是 autoInteract: false,不受影响)。
注意 CSS 必须写在
<style>里 —— 写进<script>会让整段脚本抛SyntaxError: Unexpected token '{'而不执行,页面直接废掉。
操作栏与拖动
- 操作栏在角色左侧,图标沿凹向角色的弧线排布(月亮型,中间离角色最远、两端迎向角色轮廓),无背景,只有深色图标 + 白色外发光描边(浅/深背景都能看清)
- 关闭按钮是红色(
ArcAction.danger),拖动柄拖动时变主题蓝 - 话术框与角色同宽、左边缘对齐(不再横跨整组宽度)
- 角色本体也能拖动(
GestureDetector+HitTestBehavior.translucent,点击仍穿过到下层) - 拖动时拖动柄变成主题蓝;不要用
Transform/AnimatedScale做拖动反馈 —— Android 平台视图(WebView/TextureView)不支持任意变换,一旦被 transform 包裹就整块不渲染(表现为模型消失) - 话术只有一步时,不显示上一步/下一步(
scriptSteps.length > 1才加)
话术框:手机端用 GlassSurface(液态玻璃,blur 32 + 白色 0.42),文字依然清晰;桌面分栏仍用实心白底。GlassSurface 全局默认透明度也从 0.78 降到 0.60、描边从 0.85 降到 0.62,整体玻璃感更透。
模型大小可调(模型大小 滑杆)
Live2D 的 canvas 四周留白各模型差异极大(有的角色只占 canvas 中间 40% 宽),任何固定值都会出现「这个模型显得太小、那个被裁头脚」。所以:
- WebView 加载后用
model.getLocalBounds()把比例报给PromptLink.avatarModelAspect(持久化,换模型自动作废) - 浮窗宽度 =
角色高度 × 模型比例(clamp 0.28~0.90,且有 232 的最小宽度保证话术可读) - 再加一个用户可调的
模型大小滑杆(0.8~1.8x,默认 1.0 = 完整显示不裁切),拖动时通过avatar.setZoom()实时重排,不重新加载页面 - 放大后的裁切方向:
fit()在模型高于容器时改为顶部对齐,多余部分从脚部裁掉 —— 保证脸和上半身永远完整(之前是贴底对齐,放大后y<0会裁头) - 两种渲染引擎都支持「模型大小」滑杆:WebView 走页面内 �vatar.setZoom() 重排;原生走特殊参数 / 插件 channel(zoom / setZoom),C++ 把它乘到适配缩放上
- 之所以要能调:原生按「角色本体边界 contain」适配合,遇到 canvas 留白大或没有边界数据时会比 WebView 略小
- 原生后端按角色本体做 contain 适配(
ApplyViewportFit,见tool/patch_live2d_plugin.dart)- 投影每帧做各向异性补偿(竖容器
Scale(H/W, 1)、横容器Scale(1, W/H)), 满足P_x·M_x·W == P_y·M_y·H,模型在屏幕上不变形 - 本体边界用插件每帧
Update()后算好的 drawable 顶点并集(GetContentBounds, 模型空间)—— 实测 Hiyori 本体bh≈1.27 < canvas ch=1.4,是能装下整个角色的 - 缩放取两轴较小者(
s = min(2/(px·fw), 2/(py·fh)) · margin,margin 0.92) = contain(完整放入、绝不裁切),对任意视口都只做居中 contain; 之前按 canvas 做 cover(SetHeight/SetWidth填满)会在竖容器里裁掉头/脚 - 平移让本体中心映射到视口中心:
t = −s·本体中心(TranslateRelative) - 贴边收起用「动态宽高」而非「缩到窄条 + 贴角 + 裁角」:旧裁角方案依赖平台视图
出屏溢出的映射,在 Android 混合合成下左右贴边不对称、且角色贴到出屏交界线会被裁脚。
现由
FloatingAvatarHost._buildUnit在贴边时把平台视图直接 resize 到窄条尺寸 (widget 树类型/层级在展开与紧凑间保持一致 → Live2dAvatar 只被 resize、不被 remount), 原生/WebView 均对整视口居中 contain → 左右天然对称、身体完整,彻底不碰裁角/交界线 __fit_cx__/__fit_cy__/__fit_w__/__fit_h__仍由 Dart 下发并存进view->fitBounds, 但当前不再读取 —— 原生改用自带的GetContentBounds,纯原生后端(无 WebView 量边界)也能正确适配
- 投影每帧做各向异性补偿(竖容器
排查时踩的坑:
index.html改动后不需要手动升版本了:Live2dService.computeAssetVersion()会把index.html的内容哈希算进版本号,改了文件一定会重新释放。这个 bug 曾导致「改了代码但设备上还是旧页面 → 脚本整段不执行 → 模型加载不出来」排查很久- WebView 会缓存
index.html,URL 里必须带v=<资源版本>参数破缓存 modelAspect()里不能直接写model—— 它在boot()的闭包里,对象方法访问会ReferenceError,必须走avatar._model- PowerShell 写 Dart/JS 文件时会吃掉
&&、把$var展开成空,涉及这两样时用编辑工具而不是 shell 重定向 模型适配的「放大系数」:Live2D 的 canvas 通常比角色本体大一圈,纯Math.min适配会让角色显得很小、两侧空一大片。WebView(index.html)允许高度方向多溢出(fitOverscan,由「模型大小」滑杆 0.8~1.8x 实时调)。原生(live2d_flutter.cpp)则不带溢出、直接按本体 contain(展开margin0.99 / 贴边 0.86)—— 优先保证角色完整不裁切(展开态与贴边都不切头脚),代价是角色比 WebView 侧略小、四周留白略多。
为什么改成「以高度定宽度」:Live2D 人物模型本身是竖长的(宽高比约 0.5~0.7)。早期把角色盒做成横向(420×330),模型按高度适配后宽度只用了一半,两侧全是空白 —— 就是「数字人比框小很多、看着松散」的原因。改成竖比例后模型宽度利用率从 ~52% 提到 ~71%,整组宽度也从 460 收窄到 327。
WebView 侧的适配系数同步从 0.96 提到 0.99(几乎贴边),见 assets/live2d/index.html 的 fit()。
数字人有两种渲染后端,可在「双机联动播报 → 数字人 → 模型与展示 → 渲染引擎」里切换:
| 后端 | 实现 | 平台 | 状态 |
|---|---|---|---|
| WebView | WebView + PIXI + Cubism Web SDK | 全平台 | ✅ 稳定,长期验证 |
| 原生 | Cubism Native SDK + OpenGL ES 2(flutter_live2d) |
Android / iOS | ✅ 可用(构建前需跑补丁脚本,见下节) |
| 原生 | Cubism Native SDK + OpenGL 3.3 离屏 + 外部纹理(仓内 plugins/flutter_live2d_windows) |
Windows | ✅ 可用 |
默认后端按平台选(kDefaultAvatarBackend):
- Windows 默认「原生」:WebView2 会常驻
msedgewebview2.exe(浏览器进程 + GPU 进程 + 渲染进程),内存占用明显高于原生;原生是外部纹理,在同一个进程内合成 - Android 默认「原生」:WebView 要起一整个 Chromium 内核,再加页面里的 PIXI / Cubism Web SDK;原生走 SurfaceTexture,占用和启动都快一截
- macOS / Linux 默认「WebView」:没有原生实现
flutter_live2d 的本地补丁:构建前必须跑
dart run tool/patch_live2d_plugin.dart(补丁内容见 tool/patches/),
否则原生后端初始化会失败(表现为数字人区域空白 + 错误提示)。
- 选择会记住(
prompt_avatar_backend),重启后保持 - 切换后数字人立即按新后端重新加载,模型/嘴型/导入逻辑完全复用
- 当前平台不支持的后端会置灰(macOS / Linux 没有原生实现)
默认值变更时老用户怎么办(prompt_avatar_backend_v)
改默认值对已装用户无效 —— 他们 prefs 里存着旧值。所以加了一个版本标记:
- 老用户没有这个标记 → 首次升级到本版时套用一次新默认(Android 从 WebView → 原生)
- 之后用户手动切换后端,会同时写入版本标记 → 不再被默认值迁移覆盖
- 想回到 WebView:设置页手动切一次即可(会一直记住)
占用相关的两个事实:
- WebView 页面渲染限制在 30fps(
app.ticker.maxFPS = 30,PIXI 默认 60)—— 数字人动作 30fps 够用,CPU/GPU 占用直接减半,也与原生后端一致 - WebView2 进程在切到原生后不会立刻退出:插件的 Environment 是引用计数 (最后一个 controller dispose 时才销毁),但 WebView2 自身的进程回收有延迟, 且可能与系统里其他 Edge WebView2 应用共享进程。要彻底释放,重启应用即可 —— 所以 Windows 上默认不启动 WebView2 才是最有效的降占用方式
原生后端踩过的坑(5 个,全部已修)
上游插件的 3 个(详见后文「两个上游 bug 与修复」一节,实际是 3 个):GL context 初始化时机、shader 未打进 APK、SetWidth 导致瘦高模型裁成半身。
我们这边的 2 个:
Live2DView必须始终在 widget 树里 —— 插件的 controller 靠视图挂载才_attach(),whenAttached才 resolve;按加载状态决定是否渲染它会造成死锁- 加载中不要上报错误 —— 一旦上层用错误框替换掉
Live2DView,插件立即 detach,后续loadModel全部VIEW_NOT_ATTACHED SurfaceTexture是异步创建的 —— 视图刚挂载时原生侧width=0,nativeLoadModel会直接失败,需要重试(已加 4 次重试)
代码结构:
lib/services/avatar_renderer.dart # AvatarRenderer 抽象 + AvatarBackend 枚举 + 平台可用性
lib/widgets/live2d_avatar.dart # 壳:按后端创建 renderer,转发嘴型
lib/widgets/renderers/webview_avatar_renderer.dart # WebView 实现
lib/widgets/renderers/native_avatar_renderer.dart # 原生实现
代价:APK +4MB(Cubism Core 静态库),Android 构建需要 CMake 3.10.2 + NDK 27.2(CI 已自动安装)。
新增 lib/widgets/glass_surface.dart,提供统一的玻璃质感组件:
| 组件 | 用途 |
|---|---|
GlassSurface |
玻璃容器:背景强模糊(BackdropFilter)+ 半透明渐变 + 1px 高光描边 + 柔和投影 |
GlassNavBar |
悬浮玻璃导航条(联动页底部) |
GlassNavItem |
导航项,选中时是更亮的一小块玻璃 |
GlassActionButton |
悬浮玻璃主按钮(首页「开始拨号」「选择 Excel 文件」) |
- 联动页底部标签栏从「占布局空间」改成悬浮在内容之上的玻璃条(内容区留了 96px 底部空白,不会被遮住)
- 首页的主操作按钮也改成悬浮玻璃按钮(列表里不再有重复的大按钮)
- 玻璃模糊需要背后有内容才看得出来,所以两个页面都把按钮放在内容之上(
Stack+Positioned),而不是放在bottomNavigationBar
「双机联动播报」页改成 常驻快捷条 + 4 个标签页:
| 位置 | 内容 |
|---|---|
| 常驻快捷条 | 拨号端 / 播放端胶囊开关(点一下切换)、连接状态与「扫描设备」按钮、**「立即播报」**主按钮;无障碍未开启时额外出现「开启检测」快捷入口 |
| 连接标签 | 通话检测服务(无障碍状态 + 跳转设置)、设备名、单机自测 |
| 播报标签 | 开场白文本 + 语速、端侧语音合成、开场白音频 |
| 数字人标签 | 数字人开关、模型与展示(切换模型 / 导入 zip / 演示模式 / 复位位置) |
| 日志标签 | 运行日志、使用要点 |
- 角色开关从长列表挪成了顶部小胶囊,不用滚动就能开关角色、连对端、立即播报
- 每个标签页内部仍可滚动,但首屏就能看到该页的主要操作
- 两台手机连同一个 Wi-Fi,都安装本应用
- 打开应用右上角 🎤 图标进入「双机联动播报」
- 所有角色默认都是关闭的,按需打开(开关状态会被记住,下次打开 App 自动生效):
- 拨号端:打开「拨号端:接通后自动通知播放端」,并点「打开系统无障碍设置」→ 找到「话务助手」→ 开启 (未开启时页面顶部会显示橙色「未开启」,接通检测不会工作)
- 播放端:打开「播放端:收到指令后朗读开场白」,把音量调到 60~80%
- 连接对端(播放端操作):点顶部「扫描设备」→ 从弹出的列表里选一台拨号端
- 列表只显示同一 Wi-Fi 下 15 秒内有心跳的设备,随心跳实时刷新
⚠️ 不会自动连接:同一网段经常有好几台设备都在跑本应用(同事都用), 自动连会连到别人那台;现在必须由你手动挑- 列表为空时按弹窗里的提示检查:两台在同一 Wi-Fi、对端已开启对应角色
- 设置开场白(三选一,推荐音频):
- 点「开场白音频 → 选择音频文件」,导入一段真人录音(mp3/wav/m4a/ogg),保留原后缀存成
opening_audio.mp3这种形式,能直接看出格式 - 或点「用麦克风录制」,直接念一遍(存成 16kHz 单声道 wav)
- 或者用「开场白文本」交给系统 TTS 朗读(部分 ROM 的 TTS 不对第三方开放,见下方注意事项)
- 想用端侧合成:在「端侧语音合成」卡片里点**模型下载链接(可点击跳转)**下载模型,传到手机后点「导入模型包」,再点「生成语音」
- 回名单页正常拨号;对方接通后播放端会自动朗读/播放
| 开关 | 默认 | 记忆方式 | 打开后自动初始化 |
|---|---|---|---|
| 拨号端 | 关 | SharedPreferences |
局域网通道 + 通话状态监听(无障碍检测接通) |
| 播放端 | 关 | SharedPreferences |
局域网通道(接收播报指令) |
| 数字人 | 关 | SharedPreferences |
Live2D 资源释放 + 本地 HTTP 服务(否则模型会 404) |
- 角色与数字人开关默认全部关闭,首次安装不会自动跑任何后台服务
- 手动改过之后配置会固化,下次打开 App 自动按配置初始化对应服务(关掉的角色不监听 47823 端口、也不订阅无障碍事件)
- 两个角色都关着时 App 不占端口、不订阅通话状态,省电也少权限
为什么推荐音频文件:实测小米 HyperOS 的系统 TTS(
com.xiaomi.mibrain.speech)不对第三方应用开放,TextToSpeech初始化直接返回-1,App 无法让系统引擎发声。换成真人录音播放,既绕过引擎限制,声音也更自然、更不容易被听出是合成的。
既想「文本可改」又不想依赖系统 TTS,可以让 App 用内置的 sherpa-onnx 离线合成一次,把开场白变成 wav 缓存下来,之后每次接通只播 wav:
编辑开场白文本 → 点「生成语音」(本机合成 2 秒左右,只做一次)
↓
缓存 opening_tts_<ts>.wav(自动设为播报音频)
↓
接通 → 广播 → 播放端直接播 wav(延迟 ≈ 0,不等合成)
安装模型(一次性,13.4MB)
- 下载
vits-piper-zh_CN-xiao_ya-medium-int8.tar.bz2(13.4MB) https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models - 把
.tar.bz2传到手机 - App 内「双机联动播报 → 端侧语音合成 → 导入模型包」,选这个文件
- 状态变为「模型就绪」后,点「生成语音」即可
模型解压到 Android/data/com.callassistant.call_assistant/files/sherpa-tts/(可用 adb 直接推),也可手动放模型目录后重启 App 自动识别。
模型架构自适应(TtsArch)
不再写死 VITS,按模型目录里的文件特征自动识别:
| 目录里的特征 | 判定的架构 | 用的 config |
|---|---|---|
有 vocoder.onnx |
Matcha | acousticModel + vocoder |
有 voices.bin |
Kokoro | model + voices |
其余(model.onnx + tokens.txt) |
VITS | model + tokens |
所有架构都会自动带上(存在时):espeak-ng-data/、lexicon.txt、dict/(jieba 词典)。
模型选择建议
| 需求 | 模型 | 体积 | 语言 | 下载 |
|---|---|---|---|---|
| 只要中文、省空间 | vits-piper-zh_CN-xiao_ya-medium-int8 |
13.4MB | 中文 | 下载 |
| 多语言 + 音质更好 | kokoro-multi-lang-v1_1(int8) |
约 86MB | 中/英/日/法/西/印地/意/葡 | 下载 |
| 中英混读 | matcha-icefall-zh-en + vocoder |
约 70MB | 中英 | 下载 |
这几项在 App 内也能直接点:端侧语音合成卡片里点「模型下载」会弹出同样的清单, 点条目即跳直链下载(
_showTtsModels);识别的「下载模型」按钮同理(_showAsrModels)。
Kokoro 的多语言模型如果要指定语言,在模型目录里放一个 lang.txt(内容如 zh / en / ja);
不放则交给引擎按默认(英文)处理。piper 那类单语言模型不需要这个文件。
实测数据(小米 2410DPN6CC / Android 17)
| 环节 | 耗时 |
|---|---|
| 解压 13.4MB 模型包 | ~1.0 s |
| 首次合成(含模型加载,约 24 字) | ~2.1 s |
| 后续合成(模型常驻) | 明显更快 |
| 播报时(播 wav) | 启动 < 100 ms |
生成的是 16bit PCM 单声道 wav,语速由文本卡的「语速」滑块换算成
speed参数。模型只在合成时用到,不打包进 APK。
播报时界面上会有一个 Live2D 数字人做说话口型,嘴型与语音音量严格同步(只在本机屏幕可见,对方在通话里看不到画面)。
浮窗结构(上:角色 + 操作栏,下:话术框)
展开态 贴边态(微信通话「最小化」)
┌────────────────┐ ┃⠿ ┃ 拖动 ┌──┐
│ │ ┃‹ ┃ 上一步 │🧑│ ← 小挂件 + 状态圆点
│ 角色 │ ┃› ┃ 下一步 │ │ + 恢复按钮 ↗
│ (占屏幕一半) │ ┃💬 ┃ 话术框收起 └──┘
│ │ ┃⇱ ┃ 贴边 点它/拖它即恢复
│ │ ┃✕ ┃ 关闭 (贴屏幕左/右边缘)
└────────────────┘
┌────────────────┐
│ ● 等待接通 · 张伟 │ ← 状态信息在话术框顶部
│ ─────────────── │
│ 张伟 今天16:15拨过│
│ 销售一部 │
│ 话术 1/1 │
│ 您好,我是本次项目… │
└────────────────┘
- 上下结构:上半部分「角色 + 右侧操作栏」,下半部分话术框(宽度与上方完全对齐,左边缘和右边缘都齐)
- 整体宽度约占屏幕 80%(
groupRatio = 0.8,限制在 240~460 之间),角色随之放大到约 1.6 倍;Live2D 模型本身左右留白较多,想再大就把groupRatio往 1.0 调 - 操作栏垂直居中于角色右侧(高度自适应,不与角色等高)
- 话术框可单独收起/展示:操作栏上的
💬按钮切换,收起后只剩角色 + 操作栏(图标变为空心气泡表示可展开);状态本地持久化 - 状态条并入话术框:话术框第一行就是状态(
待拨号/等待接通/播报中/异常,带颜色圆点),不再单独占一条 - 贴边收起(微信通话「最小化」样式):点
⇱或把浮窗拖到屏幕左右边缘,会缩成 116×146 的小挂件贴在边缘,只露出角色 + 状态圆点 + 恢复按钮;点挂件或直接拖动它就恢复原样(恢复后回到原位置) - 提词气泡:拨号时自动带上客户名、单位/备注(取表格前两个字段)、上次拨打时间(
今天 15:30 拨过/3 天前拨过/首次联系),以及按句拆好的话术步骤 - 位置自动记忆;贴边方向按浮窗所在的一侧自动判断
演示模式(全屏,适合录屏/给客户看)
联动页右上角数字人菜单 →「演示模式(全屏)」:与联动页同色背景 + 放大一倍的大尺寸数字人(几乎占满可用高度)+ 逐句字幕 + 进度条,话术框固定高度(至少能显示 4 行),点「开始演示」按话术播报,字幕按播报时长自动推进(有合成音频时按其真实时长,否则按字数估算)。右上角可切模型。
_demoSupported 为 false 时,菜单项与按钮都不显示)。
原因:演示页要再创建一个数字人实例,和左栏分栏那个同时存在时两者互相影响 ——
实测演示页一直是纯白、无任何提示,而左栏单独用又是正常的。原生渲染的实例创建
依赖布局尺寸链路,全屏页面 + 分栏并存时这条链路没跑通。与其留一个「点了就空白」的
入口,不如直接隐藏;WebView 后端和多实例机制都还在,将来把尺寸链路理清可以再打开。
浮窗与拖动
- 数字人是全局浮层(挂在
MaterialApp.builder上),因此浮在所有页面之上:首页、名单列表、联动配置页都能看到,不随页面滚动 - 背景完全透明:没有底板、没有阴影,只画角色本身,页面文字可以透过角色周围正常阅读
- 按住数字人底部的小胶囊拖动条即可拖到屏幕任意位置(自动夹在可视区域内),松手后位置写入本地,重启仍保持
- 胶囊右侧的 ✕ 直接关闭(等同关掉联动开关);卡片里的「复位」按钮回到默认右上位置
- 尺寸固定 300×380(+40 控制条),便于看清模型细节;想调小改
FloatingAvatarHost.avatarWidth/avatarHeight - 平台视图(WebView)会吃掉自身范围内的触摸,所以拖动条与 ✕ 都放在视图外面;角色身体覆盖到某个按钮时,把它拖开即可
- 实现上两个坑:①
Live2dAvatar不能自带底色、也不能套IgnorePointer(会让 Android 层把这一带触摸直接派给 WebView,连控制条都点不动);② 必须保留ClipRect约束平台视图的触摸区域
实现方式
| 环节 | 做法 |
|---|---|
| 渲染 | webview_flutter + pixi-live2d-display + Cubism 5 Core(打包在 assets/live2d/,5.4MB) |
| 托管 | file:// 下 WebView 的 fetch 会被 CORS 拦,因此把资源释放到应用目录后用 127.0.0.1 静态服务托管(Live2dService) |
| 唇形 | 合成 wav 时顺带算振幅包络(每 50ms 一个 RMS 值,存 *.wav.env.json)→ 播放时按播放位置查表 → JS 设置 ParamMouthOpenY |
| 平滑 | JS 侧按帧向目标值插值(0.35 系数),避免嘴型跳动 |
| 兜底 | 没有包络(用户自选 mp3/ogg)或走系统 TTS 时,用正弦+随机包络的程序化口型 |
模型
内置 8 个 Live2D 官方样例模型(assets/live2d/,共约 22MB),右上角数字人菜单 →「切换已有模型」即可逐个试:
| 目录 | 模型 | 体积 | 备注 |
|---|---|---|---|
haru/ |
Haru | 3.1 MB | 带 8 个表情(expressions) |
hiyori/ |
Hiyori | 4.7 MB | 默认,10 个动作 |
mao/ |
Mao | 4.1 MB | 带表情 |
mark/ |
Mark | 0.7 MB | 体量最小,风格化角色 |
natori/ |
Natori | 3.3 MB | 带表情(exp/) |
rice/ |
Rice | 3.0 MB | 小动物风格 |
wanko/ |
Wanko | 0.7 MB | 1024 贴图 |
授权提醒:这些都是 Live2D 官方样例模型,仅允许测试/非商业用途,对外发布必须替换成自有或已购买授权的模型。
关于 Cubism 3 格式的模型:内置运行时是 Cubism 5 Core,只支持 moc3 v5 及以下(= Cubism 4/5);Cubism 3 的模型是 moc3 v6,且官方运行时早已移除 Cubism 3 实现、Cubism 3 Core 也不再公开分发,因此这类模型无法加载(官方样例里的 Ren 就属于这一类,已从内置列表移除)。App 仍会按 moc 文件头版本号自动过滤这类模型,万一手动指定了它,页面会给出明确提示而不是英文报错。 判据是 moc 文件头的版本号(不是 model3.json 里的
Version——那个字段 Cubism 4 也是 3)。
- 自备模型:打包成 zip(内含
*.model3.json及贴图/动作/表情文件)→ 数字人菜单 →「导入模型包(zip)」→ 释放到Android/data/<包名>/files/live2d/models/<名字>/ - 首次启动会把 assets 里的运行时与模型解压到应用目录(约 22MB,
Live2dService.assetVersion控制是否重新释放) - 想换默认模型:改
Live2dService.defaultModel(如haru/Haru.model3.json)
实测(小米 2410DPN6CC / Android 17)
[Live2D] mouth=0.52 smooth=0
[Live2D] mouth=0.52 smooth=0.16
[Live2D] mouth=0.17 smooth=0.31
[Live2D] mouth=0.64 smooth=0.48
smooth 是模型里实际生效的 ParamMouthOpenY,会平滑跟随包络目标值,说明唇形链路正常。
已知限制
- WebView 是平台视图(混合合成),会遮挡紧邻的 Flutter 控件 —— 所以「导入模型」「切换模型」放在标题栏菜单
- 浮层位于 Navigator 之上,因此打开对话框 / 底部面板时数字人依然浮在最上面(把它理解成桌面挂件即可);不想要就点 ✕ 关掉
- 演示模式(全屏)会自动隐藏浮窗,避免出现两个角色并挡住字幕
- 个别 ROM 的 WebView 若关闭 WebGL,会显示「数字人加载失败」,功能不受影响(只影响动画)
- 数字人只在本机屏幕上,通话对方看不到;要做给客户看的画面需要视频通话/录屏,是另一套方案
- 必须让浮窗「点击穿透」:平台视图(WebView)本身会吃掉它覆盖区域的全部点击;
Material/ 带decoration的Container/ClipRect同样会吃点击。做法是:角色区、状态条、气泡统统IgnorePointer,控制条保持可交互;Live2dAvatar里的IgnorePointer必须包在ClipRect外面。 - 必须有
DefaultTextStyle:浮层挂在MaterialApp.builder上、没有Material祖先,文字会落到 Flutter 的 fallback 样式(标志性的红字 + 黄色双下划线)。用DefaultTextStyle(style: Theme.of(context).textTheme.bodyMedium!)包一层即可。 - 平台视图走的是纹理合成(
displayWithHybridComposition默认 false),命中测试由 Flutter 决定,所以IgnorePointer才有效。 - 放进
Row后要给固定宽度:Row的非 flex 子节点拿到的是无界宽度,Live2dAvatar里的width: double.infinity会变成无限宽,平台视图直接渲染不出来(现象:只剩气泡、角色消失)。外面套一层SizedBox(width: 300)即可。
| 项 | 说明 |
|---|---|
| 接通判定 | 依赖通话界面的计时器/「通话中」文案,不同 ROM 界面不同,已在代码里按包名过滤(dialer / incallui / contacts / phone / call),个别机型可能需要调整匹配规则 |
| 系统 TTS | 小米 HyperOS 的引擎对第三方关闭绑定(TextToSpeech 初始化 status: -1),此时必须用「开场白音频」;Android 原生/多数 ROM 用 adb shell settings get secure tts_default_synth 可查看默认引擎 |
| 强制停止 | MIUI/HyperOS 上「强制停止」应用会被系统移除无障碍授权,需要在设置里重新开启。已用前台保活服务规避:拨号端开启时 App 会常驻前台服务,进程不会被系统回收(实测 am kill 杀不掉),授权不会自己掉。仍被用户手动「强制停止」的话只能重新授权 |
| 自检方法 | 接不上时先看页面底部「运行日志」:已连接拨号端 = 播放端已连上;检测到接通 = 无障碍生效;收到播报指令 = 播放端收到;开始播放音频 = 音频已触发。日志只在连接/断开时记录,不会被心跳刷屏 |
| 降噪干扰 | 拨号手机若开启「AI 通话降噪 / 人声增强」,可能削弱播放端的外放声,建议关闭 |
| 拾音位置 | 开免提时麦克风在底部,关免提时在上部,播放端要对准对应麦克风 |
| 后台存活 | 系统省电策略建议设为「无限制 / 允许后台运行」,否则通话中进程被回收会导致检测中断 |
| 端口 | UDP 47823;路由器若屏蔽 255.255.255.255 广播,会自动改为向已发现对端单播 |
连接方式(播放端主动 → 手动选择)
播放端点「扫描设备」
└─ 广播 query(每 2 秒重试,最多 15 次)
└─ 拨号端收到 query → 回 hello(role=dialer)
└─ 列表 = lan_link.peers(15 秒内有心跳的对端,按名字排序)
└─ 用户点某一台 → 单播 connect
└─ 拨号端回 connected → 双方标记「已连接」
hello 就直接发 connect,同一 Wi-Fi 下
多台设备同时跑本应用时会连到别人那台(多个播放端也会抢同一个拨号端)。
现在 hello 只用来刷新设备列表,必须由用户从列表里挑 —— 见
PromptLink.discoveredPeers / connectToPeer,UI 在 _showDevicePicker。
接通后会发一条系统通知
接通那一刻人往往不在界面上(手机放在桌上),光看日志来不及确认有没有通知到。 现在接通后会发一条通知,标题直接写明结果:
| 通知标题 | 含义 |
|---|---|
| 已通知播放端 | 已连接,正文带客户标签 + 对端设备名 |
| 已广播(未连接) | 列表里有在线播放端,但不保证它在播 |
| 播报可能未送达 | 没有检测到在线的播放端 |
| 播报未发送 | 局域网未启动(角色被关掉了) |
| 已本机播报 | 双角色,本机自己念的 |
通知用独立 channel(call_assistant_broadcast),和前台服务的常驻通知分开,
可以单独静音;固定 id,后来的覆盖前一条(只看最新一次)。Android 13+ 需要通知
权限,开启拨号端时会自动请求。
按平台只走一条通道(一次播报只出一条,不会重复)
| 平台 | 用的通道 |
|---|---|
| Windows 10/11 | 应用内浮层 + 系统 Toast(两者作用不同:浮层在窗口内立刻可见,Toast 进通知中心、最小化也看得到);系统通知固定 identifier + 2 秒去重,不会叠两条 |
| Android | 应用内浮层 + 状态栏通知(浮层不怕权限被拒,状态栏锁屏可见) |
双栏统一液态玻璃(desktop_split.dart / prompt_page.dart)
- 右栏所有页面顶部都是玻璃:
HomePage/PromptPage/ 号码列表页的AppBar统一半透明白0.92+ 无阴影 +surfaceTintColor透明;Scaffold背景统一0xFFF1F5FF - 两栏顶部严格等高(各 56 + 8 + 98 = 162)
- 关键:右栏是带 AppBar 的整页,左栏没有 → 之前永远差 56px
- 左栏补了一个 56 高的标题栏(
数字人,与 AppBar 同风格),下面才是 98 高的玻璃块
- 顶部玻璃块:圆角 20 / blur 24 / opacity 0.94(0.82 时下面的内容会透上来,字看不清)
- 左栏:图标
19+ 11px 小字「已显示 / 已隐藏」+Switch,第二行「渲染后端 · 当前模型」 —— 与底栏_ActionArea的「图标 + 小字」是同一套视觉语言 - 右栏:角色胶囊(开时蓝色
0xFF2F6BFF)+ 连接状态 + 立即播报 / 停止
- 左栏:图标
- 两栏底部都是悬浮
GlassNavBar(Positioned(bottom: 14))- 左栏一行三项:上一步 / 下一步 / 切模型(图标 + 11px 短文字,不再用整行按钮)
- 右栏一行四项:连接 / 播报 / 数字人 / 日志
- 左栏背景是浅蓝渐变(
0xFFEDF2FE → 0xFFF7F9FC → 0xFFF1F5FF), 右栏Scaffold取渐变中间色(0xFFF1F5FF),两栏看不出分界;玻璃块才有东西可透 - 左栏数字人卡片改半透明白(0.72)+ 白色描边,跟着玻璃走
- 右栏
AppBar半透明白(0.72)+ 无阴影
收到播报指令时也会弹「正在播报 · <客户标签> · 来自 <设备名>」,窗口最小化时能看到。
Windows 的 Toast 需要「开始菜单里有匹配 AUMID 的快捷方式」,
local_notifier首次 setup 会自动建一个「话务助手」快捷方式 —— 这是local_notifier的实现要求,别删。 如果不想在开始菜单留快捷方式,可以改用 Win32 托盘气泡(Shell_NotifyIcon+NIF_INFO), 那个不需要快捷方式,Win10/11 上同样进通知中心 —— 需要自己写一个 C++ 小插件。
手动推送开场白到播放端(已连接时)
播报时不会自动传音频(每通电话都等一次传输,接通到出声会变慢),改成两个手动按钮:
- 「开场白音频」卡片 → 发送到播放端:对方拉下来后自动设为它的开场白音频
- 「开场白文本」卡片 → 发送文本到播放端:对方直接填成它的开场白文本
音频走单播 TCP(端口 47824 = UDP 端口 + 1),协议 [4 字节大端长度][文件内容]:
拨号端点「发送到播放端」
└─ 音频挂到 TCP 服务,广播 push_audio(带 deviceId)
└─ 播放端核对是不是自己那条连接 → 单播拉取 → 存 audio/from_dialer.wav
└─ 自动设为本地开场白音频(覆盖原来那份)+ 发一条通知
限制:单文件 8MB(60 秒 wav 约 2MB);只在已连接时可用(单播需要对方 IP);
断开连接会收掉 TCP 服务。文本走 push_script 消息,直接带内容,不占用 TCP。
音频只需要在「会播的那一端」有
- 只当拨号端:不需要本机音频 —— 播报文本广播给播放端,由它用自己的音频/TTS 念
- 双角色(本机自己播)或桌面端:本机要念,所以需要音频
点「立即播报」时按这个规则检查,只当拨号端不会再被要求设置音频。
连接时会有明确反馈
- 点设备后立刻显示转圈(避免以为没点上而反复点)
- 连上:列表项变绿「已连接」,并关闭弹窗;状态卡片里显示完整设备名
- 连不上:5 秒后给出原因 —— 对方没开启拨号端 / 已被其他播放端占用 / 不在同一 Wi-Fi (以前点了完全没反馈,只有 30 秒后一条日志)
一个拨号端只接一个播放端
connect 分支会检查:已经连着别的播放端 → 回 busy 并拒绝(日志写明被谁占用)。
否则多个播放端同时连上,接通时会一起播(多台同时响),状态也会被后连的覆盖。
没开拨号端时也回 busy,避免对方白等 15 次重试。
关掉角色会自动断开
- 关「播放端」:与拨号端的那条连接没意义了 → 主动断开并通知对方
- 关「拨号端」:已连的播放端必须跟着断(否则它还会继续往这里播)
- 手动点「断开」同样会通知
通知走广播 bye(带 deviceId,对端自己匹配)—— 断开时对端可能已从 peers
列表过期,拿不到 LanPeer 就没法单播。对端收到 bye 只清本地状态,
不会再回一个 bye(否则两边无限对发)。
- 不需要双方都开:拨号端只要开着就在线,播放端点一下按钮就能连上
- 日志只在连接成功/断开时记录一条,心跳不会刷屏
- 15 秒收不到对端任何消息 → 自动判定断开并记一条「已断开连接」
- 连接建立后,接通指令、播报都走这条已建立的通道
单机自测(只有一台手机时)
同时打开「拨号端」和「播放端」即可 —— 这个组合本身就是单机自测: 拨号接通后直接本机播报,不需要连接任何设备(状态行显示「本机双角色:无需连接」)。 不用第二台手机就能验证整条链路(接通 → 播报 → 口型)。
以前有个独立的「单机自测」开关,现在这个组合已经覆盖了它的全部作用,开关已移除。
同时开两个角色时的行为
- 接通后只本机播报,不再向局域网广播 —— 以前是「广播 + 本机播」双份, 同网段如果还有别的播放端,两台会同时响(有回声 / 字幕和声音错位)
- 不接受其他设备连接:本机闭环,别的播放端来连会收到
busy并被拒绝; 也不回应设备查询(别人的扫描列表里不会出现本机) - 双角色状态下不提供「扫描设备」,状态行固定显示「本机双角色:无需连接」
- 想用另一台手机播时:把本机的「播放端」关掉、只留「拨号端」即可 —— 开着「播放端」就表示「我想用本机念」 | 隐私 | 只读取通话界面上的计时文案,不上传、不录音;无障碍服务描述中已声明 |
- 接通检测换成 默认拨号应用(
InCallService+ROLE_DIALER)→ 拿到准确的Call.STATE_ACTIVE,兼容性远好于读界面 - 播报改为服务器侧外呼(语音通知/呼叫中心)→ 无需第二台手机,音质与合规性最好
- 播放端改用预生成音频文件(去掉 TTS 首次发声延迟)
工作流:.github/workflows/release.yml,四个 job(ci /
elease-android /
elease-windows / publish):
| Job | 触发 | 产物 |
|---|---|---|
ci |
push 到 main / PR / 手动触发 | 分析 + 测试 + Debug APK(Artifact,保留 14 天) |
release-android |
打 v* 标签时 |
正式签名 APK(按 ABI 拆分,只发布 ARM 架构),重命名为 call-assistant-版本号-架构.apk |
release-windows |
同上 | Windows 免安装包 call-assistant-版本号-windows-x64.zip |
publish |
上面两个都成功 | 汇总各自产物,创建 GitHub Release |
流程(release job):checkout → JDK 21 + Flutter → 从 Secrets 还原密钥 → flutter pub get → 给 flutter_live2d 打本地补丁 → 校验标签版本与 pubspec 版本一致 → flutter build apk --release --split-per-abi → 只保留 ARM 架构并重命名 → 创建 GitHub Release。
发布产物(以 v1.2.1 为例):
| 文件名 | 体积 | 适用设备 |
|---|---|---|
call-assistant-1.2.1-arm64-v8a.apk |
~149 MB | 绝大多数现代手机(推荐) |
call-assistant-1.2.1-armeabi-v7a.apk |
~140 MB | 32 位老旧机型(Android 5~7 时代) |
call-assistant-1.2.1-windows-x64.zip |
~230 MB | Windows 10/11(需 WebView2 Runtime) |
- 用
--split-per-abi拆分后每个包只含一套 so;x86_64仅用于模拟器,不发布 - 体积比早期版本(17.5MB)大,是因为内置了离线 TTS 引擎(sherpa-onnx + onnxruntime,约 26MB so)与 Live2D 运行时 + 8 个官方样例模型(约 22MB assets);通用包会到 149MB,所以必须按 ABI 拆分
- 只想带一个模型时:从
pubspec.yaml的assets:里删掉其它模型目录,并同步清理assets/live2d/下对应文件夹(每个模型约 0.7~4.7MB) - 两个包共用同一签名密钥,可互相覆盖安装
标签推送时
cijob 会被跳过(不重复构建),只跑release;普通 push 只做 CI 校验,不产出安装包。
-
生成签名密钥(在本机执行,密钥不会提交到仓库):
pwsh -File tool/make_keystore.ps1
会生成
android/app/upload-keystore.jks和android/key.properties(两者均已在.gitignore中),并在终端打印 4 个 Secret 的值。 -
在 GitHub 添加 4 个 Secret:仓库
Settings → Secrets and variables → Actions → New repository secretSecret 内容 KEYSTORE_BASE64脚本打印的 base64 串(整行) KEYSTORE_PASSWORD脚本打印的 keystore 密码 KEY_ALIAS脚本打印的别名(默认 upload)KEY_PASSWORD脚本打印的 key 密码 -
打标签发布:
# 先把 pubspec.yaml 里的 version 改成要发布的版本号并提交 # version: 1.1.0+2 -> 版本号取 1.1.0 git add pubspec.yaml && git commit -m "chore: bump version to 1.1.0" git push origin main git tag v1.2.1 git push origin v1.2.1
标签推送后
releasejob 会跑,校验标签版本与pubspec.yaml版本一致(不一致直接报错终止),构建正式签名包并重命名为call-assistant-1.1.0.apk,挂到 GitHub Release 上。
- JDK 21(Temurin)+ Flutter 3.47.7 + Gradle 缓存,CI 与本地环境一致
- 仓库默认配置了国内镜像(本地网络需要),CI 会自动切回官方源(runner 在海外,官方源更快更全)
android/app/build.gradle.kts已改为:存在key.properties就用正式签名,否则回退 debug 签名- 发布 job 强制要求配置了签名 Secret:缺少
KEYSTORE_BASE64会直接报错终止,避免误发出 debug 签名的包 - 密钥务必备份,丢失后无法给已发布应用做更新
| 现象 | 处理方式 |
|---|---|
adb install 报 INSTALL_FAILED_USER_RESTRICTED |
手机未允许「USB 安装 / 未知来源安装」,在 设置 → 开发者选项 里打开,或安装弹窗时在手机上确认 |
| 提示「无法解析该文件」 | 只支持 .xlsx;.xls / .csv 请在 Excel 里另存为「Excel 工作簿(*.xlsx)」 |
| 手机号列识别错了 | 首页「手机号列」区域点选正确的列 |
| 点号码没反应 | 检查 Manifest 里的 <queries>;部分定制系统需要设置里允许本应用「拨打电话」 |
号码变成 1.38E+11 |
原始表格里把该列设为「文本」,本应用已做科学计数法兜底,但仍建议在 Excel 侧固定为文本 |
| 录音/一键外呼需求 | tel: 只填充不外呼;要一键外呼需改用 flutter_phone_call 或原生 ACTION_CALL 并申请 CALL_PHONE 权限 |