技术档案与架构规范 - 映辞

SECTION 01

设计背景与核心宗旨

解决传统商业提词软件过度商业化与隐私滥用的现实痛点

解决提词行业的现实困境

市面商业提词应用长期存在三大硬伤：强制手机号注册绑定、强行将隐私演讲文稿上传云端、以及高额买断/连续订阅与广告插播。在多端协同方面，双机远控大多依赖昂贵或高延迟的公网服务器中继，在演播厅、展会弱网或无网络环境下极易瘫痪。

映辞从首行代码起即确立了四个不可动摇的工程原则：

· Local-First（纯本地优先）：台本正文与配置全量存储于设备 SQLite (Room)，无云端依赖，用户掌握绝对数据控制权。

· 原生响应式排版：全栈采用 Jetpack Compose 构建，统一测量视口，手机单手与平板大屏双栏兼顾。

· 单调时钟推进：采用单调时间轴与锚点位移，杜绝刷新率波动引起的抖动与丢行。

· 无中继局域网直连：基于原生 WebSocket 实现同网段点对点通信，杜绝第三方公网中转。

· 原生 Android 专注：专为 Android 原生生态打造，全面适配 Android 手机与平板设备。暂不支持 iOS (iPhone/iPad) 苹果系统或桌面端。

SECTION 02

技术路线与架构拓扑

基于仓库真实代码提炼的技术层级流转

01

Android Runtime & Toolchain

专为 Android 平台设计：编译适配 Android 16 (API 36.1)，向下兼容至 Android 8.0 (API 26)。暂无 iOS / 苹果版本支持计划。

compileSdk 36.1 / minSdk 26

02

Kotlin & Build Pipeline

采用 Kotlin 2.2.10，Gradle 9.4.1 构建套件与协程并发流 (Flow)

Kotlin 2.2.10 / AGP 9.2.1

03

Jetpack Compose & Material 3

声明式 UI 架构，BOM 2026.02.01，单 Activity + Navigation Compose

Compose BOM / Navigation 2.9.6

04

AppContainer DI & Repository

轻量无反射延迟注入，单向数据流驱动，ViewModel 响应式状态流

Clean Architecture / UDF

05

Room & DataStore & WebSocket

版本化 SQLite Schema 存储台本，局域网 Java-WebSocket 双机点对点通信

Room 2.8.4 / Java-WebSocket 1.5.6

SECTION 03

核心依赖清单与版本

全部直接对应项目 gradle/libs.versions.toml 声明

COMPONENT / LIBRARY	VERSION	ROLE & SCOPE
androidx.compose.bom	2026.02.01	Compose 基础运行环境与版本协调
kotlin	2.2.10	主工程编译语言与标准库
agp (Android Gradle Plugin)	9.2.1	Android 官方构建工具链插件
androidx.navigation.compose	2.9.6	单 Activity 纯声明式路由导航
androidx.room	2.8.4	本地 SQLite 数据库与 Schema 版本管理
androidx.datastore.preferences	1.2.1	全局播放设置与偏好持久化
java-websocket	1.5.6	局域网提词端 Server 与控制端 Client 通信
zxing-android-embedded	4.3.0	局域网配对二维码扫码识别

SECTION 04

系统分层与数据流

单工程模块设计，清晰划分 UI、Domain、Data 边界

单向数据流与容器注入

TeleprompterApplication 初始化单一 DefaultAppContainer，负责延迟构造 Room 数据库与 Repositories。UI 层通过 ViewModel 暴露不可变 StateFlow，页面永远不直接触碰持久化底层。

Compose Screen (UI) ↓ (User Event) ViewModel / AppState ↓ (Business Intent) Repository Interface ↓ (IO / Storage) Room DAO / DataStore

提词端作为唯一状态源

在双机远控架构中，提词端是唯一真实状态源 (Single Source of Truth)。控制端发送的命令经校验后转换为业务事件；提词端将最新排版快照与阅读游标反向推回控制端，避免双向时钟分歧。

[提词端 (Server)] ── Snapshot / Window ──> [控制端 (Client)] [提词端 (Server)] <── Command (Play/Seek) ── [控制端 (Client)]

SECTION 05

本地文档解析流水线

不依赖任何第三方服务端，全流程在终端设备内存中安全流式解析

智能字符编码识别 (TXT)

自动检测文件头 BOM 标记，智能识别 UTF-8、UTF-16 LE/BE 以及中文常见的 GB18030 字符集。5 MiB 严格大小阈值校验，彻底规避乱码现象。

Word (DOC / DOCX) 纯本地提取

DOCX 基于 OOXML 规范在本地解压提取主正文段落；DOC 基于 OLE2 二进制流进行控制状态机清洗，自动跳过表格、图片、超链接与目录等干扰结构，严防 XML 外部实体攻击。

SECTION 06

局域网阅读游标同步算法

攻克双设备屏幕尺寸与折行不一致导致的长文错位问题

绝对 UTF-16 游标与滑动阅读窗口

传统提词软件双机同步多采用“直接推送屏幕可见文字字符串”的粗暴方案，一旦提词端是横屏大平板而控制端是竖屏窄手机，极易引发严重换行错乱与跳变。

映辞采用双流解耦同步算法：

· 绝对阅读游标 (Cursor)：提词端 PlaybackReadingTracker 根据实际排版几何与固定阅读锚点，持续计算全文绝对 UTF-16 字符偏移量与行内亚字符进度（约 12~20Hz 高频传输）。

· 滑动窗口 (Window)：ReadingWindowManager 维护低频约 700 字符的大上下文窗口，在游标触达前进 72% / 后退 18% 阈值时平滑滑动。

· 控制端重排版 (Retargeting)：控制端 ControllerReadingViewport 利用本地 TextLayoutResult 排版窗口文字，配合 Pending Cursor 机制，确保长文持续滚动零空白与零回跳。

SECTION 07

权限与隐私安全白皮书

透明列出应用所声明的每一项系统权限与真实代码调用场景

PERMISSION	STATUS	USAGE CONTEXT	SECURITY GUARANTEE
android.permission.INTERNET	SAFE / LAN ONLY	提词端与控制端之间建立局域网 WebSocket 连接	代码中无公网请求，不连接任何第三方中继或遥测服务。
android.permission.ACCESS_NETWORK_STATE	SAFE / LOCAL	提词端启动远控时解析当前设备的局域网 IPv4 地址	仅用于在本地生成配对二维码，不读取或上传网络标识符。
android.permission.CAMERA	OPTIONAL DYNAMIC	控制端扫描提词端配对二维码时使用	非必需硬件（required=false），支持手动输入连接信息；画面纯本地分析不上传。
外部存储读写权限	ZERO PERMISSION	文档导入基于 Android Storage Access Framework (SAF)	不申请 READ_EXTERNAL_STORAGE，单次流式读取，不长期持有文件 URI。

SECTION 08

源码获取与本地复现

基于标准开源规范，任何开发者均可直接在本地独立复现完整构建

# 克隆 GitHub 仓库 git clone https://github.com/FFocalors/teleprompter-android.git cd teleprompter-android # Windows PowerShell 编译 Debug APK .\gradlew.bat assembleDebug .\gradlew.bat testDebugUnitTest # macOS / Linux 编译 ./gradlew assembleDebug ./gradlew testDebugUnitTest

前往 GitHub 查阅完整源码