Operit 粘贴超长文本自动转文件:设置、粘贴增量识别与附件转换实现解析

原创2026-09-27 09:38:331,900 阅读
文章标签:人工智能AI AgentAI 应用移动开发工具调用GUI 自动化本地部署插件系统Agent 工作流

Operit 粘贴超长文本自动转文件:设置、粘贴增量识别与附件转换实现解析

本指南基于 Operit 仓库中 paste-long-text-as-file 系列设计文档,完整讲解"粘贴超长文本转文件"这一聊天输入优化能力的实现:包括设置项与字符阈值的设计与持久化、粘贴增量文本的识别算法、超过阈值后写入临时目录并作为 text/plain 附件进入待发送列表的完整链路,以及中英文本地化与单元测试核查方案。读完本文,你将掌握该功能的配置入口、默认行为、底层调用链与验证方法,可直接对照仓库源码进行二次开发或测试扩展。

功能背景与设计目标

在 Operit 的聊天输入场景中,用户经常从网页、文档中复制大段文本直接粘贴到输入框。改动前,聊天输入的文本变更与附件添加分属不同代码路径:粘贴操作没有被专门识别,输入框会直接保留粘贴的全部文本,也没有针对超长文本的阈值设置(详见 01-settings-and-paste-conversion.md)。

大量文本直接进入编辑器会带来两个实际问题:编辑器难以操作(滚动、定位光标、二次编辑都变得困难),大段文本也可能影响界面响应性能。

为此,该功能定义了明确的设计边界(见 index.md):

  • 只处理聊天输入框的粘贴增量:当纯文本粘贴长度超过用户设定的阈值时,创建 UTF-8 文本附件,并清空该次粘贴产生的输入内容;
  • 不改变既有路径:手动文件选择、普通文本编辑、未达到阈值的粘贴,以及消息协议与已有附件处理流程均保持原有行为。

改动的作用域集中在:聊天输入控件、持久化设置、临时附件创建和中英文资源四个层面。

设置项与阈值持久化:默认 3000 字符

持久化键与默认值

设置项存储在 UserPreferencesManager 中,使用 DataStore 的 intPreferencesKey / booleanPreferencesKey 定义键名:

  • 功能总开关:convert_long_pasted_text_to_file(布尔值),默认 开启;
  • 字符阈值:long_pasted_text_file_threshold(整数值),默认 3000。

对应实现位于 UserPreferencesManager.kt,默认值常量定义为:

const val DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD = 3000

读取与写入通过 Flow 与挂起函数暴露(UserPreferencesManager.kt):

val convertLongPastedTextToFile: Flow<Boolean> =
    context.userPreferencesDataStore.data.map { preferences ->
        preferences[CONVERT_LONG_PASTED_TEXT_TO_FILE] ?: true
    }

val longPastedTextFileThreshold: Flow<Int> =
    context.userPreferencesDataStore.data.map { preferences ->
        preferences[LONG_PASTED_TEXT_FILE_THRESHOLD]
            ?: DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD
    }

写入方法(UserPreferencesManager.kt):

suspend fun saveConvertLongPastedTextToFile(enabled: Boolean) {
    context.userPreferencesDataStore.edit { preferences ->
        preferences[CONVERT_LONG_PASTED_TEXT_TO_FILE] = enabled
    }
}

suspend fun saveLongPastedTextFileThreshold(threshold: Int) {
    context.userPreferencesDataStore.edit { preferences ->
        preferences[LONG_PASTED_TEXT_FILE_THRESHOLD] = threshold
    }
}

未显式配置时,两个 Flow 分别回落到 true 与 DEFAULT_LONG_PASTED_TEXT_FILE_THRESHOLD,即用户升级后功能默认可用、默认阈值为 3000 字符。

设置界面的开关与阈值输入

设置项位于"全局显示设置"界面(GlobalDisplaySettingsScreen),由两个 UI 组件组合而成(GlobalDisplaySettingsScreen.kt):

  1. 功能开关:DisplayToggleItem,标题为"超长粘贴文本转文件",副标题说明"粘贴超过设定字符数的文本时,自动作为文本附件添加",勾选状态直接绑定 convertLongPastedTextToFile Flow;
  2. 条件显示的阈值输入:仅在开关打开时显示 EditableNumberSetting,标题"转换阈值",说明"粘贴文本超过此字符数时转为文件",单位为"字符",取值范围为 1_000f..100_000f(即 1000~100000 字符),输入即通过 saveLongPastedTextFileThreshold(threshold.toInt()) 落盘。
if (convertLongPastedTextToFile) {
    EditableNumberSetting(
        title = stringResource(R.string.long_pasted_text_threshold),
        subtitle = stringResource(R.string.long_pasted_text_threshold_desc),
        value = longPastedTextFileThreshold.toFloat(),
        onValueChange = { threshold ->
            scope.launch {
                userPreferences.saveLongPastedTextFileThreshold(threshold.toInt())
            }
        },
        valueRange = 1_000f..100_000f,
        unitText = stringResource(R.string.long_pasted_text_threshold_unit),
        backgroundColor = componentBackgroundColor
    )
}

聊天主界面(AIChatScreen)同样通过 collectAsState 读取这两项设置,作为粘贴处理的运行参数(AIChatScreen.kt)。

粘贴增量识别:比较粘贴前后的新增区间

粘贴识别的核心算法位于 extractClipboardPastedText(PastedTextAttachment.kt)。它的输入是粘贴前的输入框状态 previous、粘贴后的 proposed,以及剪贴板文本 clipboardText,输出是"本次粘贴实际新增的区间文本"。

算法分四步:

  1. 空剪贴板直接返回 null;
  2. 计算插入区间:取 previous.selection 的起止位置(归一化到文本长度内),insertionStart 为选区起点、insertionEnd 为选区终点,从而得到粘贴前文本的 prefix(光标前)与 suffix(光标后)——这同时兼容"光标处插入"与"选中文本后被替换"两种粘贴形态;
  3. 校验前后缀:若 proposed.text 不是以 prefix 开头或以 suffix 结尾,说明本次文本变更并非单纯粘贴(可能夹杂输入法/自动纠错等),返回 null;
  4. 截取增量并与剪贴板比对:从 proposed 中截取 prefix.length 到 proposed.text.length - suffix.length 之间的子串,即粘贴新增区间;再通过归一化换行后与剪贴板内容逐字符比对,只有完全一致才认定为一次真实粘贴。
internal fun extractClipboardPastedText(
    previous: TextFieldValue,
    proposed: TextFieldValue,
    clipboardText: String,
): String? {
    if (clipboardText.isEmpty()) return null

    val previousText = previous.text
    val selectionStart = previous.selection.start.coerceIn(0, previousText.length)
    val selectionEnd = previous.selection.end.coerceIn(0, previousText.length)
    val insertionStart = minOf(selectionStart, selectionEnd)
    val insertionEnd = maxOf(selectionStart, selectionEnd)
    val prefix = previousText.substring(0, insertionStart)
    val suffix = previousText.substring(insertionEnd)

    if (!proposed.text.startsWith(prefix) || !proposed.text.endsWith(suffix)) return null

    val pastedEnd = proposed.text.length - suffix.length
    if (pastedEnd < prefix.length) return null

    val pastedText = proposed.text.substring(prefix.length, pastedEnd)
    return pastedText.takeIf {
        normalizeLineEndings(it) == normalizeLineEndings(clipboardText)
    }
}

其中 normalizeLineEndings 将 \r\n 与 \r 统一为 \n,以兼容不同平台复制文本的换行差异:

private fun normalizeLineEndings(text: String): String {
    return text.replace("\r\n", "\n").replace('\r', '\n')
}

单元测试验证

仓库在 PastedTextAttachmentTest.kt 中为该算法提供了四个方向的测试用例:

  • 光标处插入:extractClipboardPastedText(previous, proposed, "inserted ") 应返回 "inserted ";
  • 替换选区:粘贴文本覆盖已有选区时返回替换后的内容 "replacement";
  • 换行归一化:剪贴板为 "first\r\nsecond" 时,识别结果应归一化为 "first\nsecond";
  • 负例:当文本变更内容与剪贴板不一致时返回 null,避免把非粘贴输入误判为粘贴。

这四个用例恰好覆盖了算法的成功路径、选区替换路径、跨平台换行兼容路径与误判防护路径,可作为后续改动时的回归基线。

触发判定与文本落地:从剪贴板到待发送附件

输入变更钩子中的判定逻辑

AIChatScreen 的 handleUserMessageChange 是粘贴处理的入口(AIChatScreen.kt):

fun handleUserMessageChange(value: TextFieldValue) {
    val clipboardText = clipboardManager.primaryClip?.getItemAt(0)?.text?.toString()
    val pastedText =
        if (convertLongPastedTextToFile && clipboardText != null) {
            extractClipboardPastedText(userMessage, value, clipboardText)
        } else {
            null
        }

    if (
        pastedText != null &&
            pastedText.length > longPastedTextFileThreshold &&
            !currentChatId.isNullOrBlank()
    ) {
        coroutineScope.launch {
            // Keep the draft unchanged until the attachment has been created, so I/O errors do not lose text.
            if (!actualViewModel.attachPastedText(pastedText)) {
                commitUserMessageChange(value)
            }
        }
        return
    }

    commitUserMessageChange(value)
}

判定条件由三个因素共同决定,缺一不可:

  1. 功能开关 convertLongPastedTextToFile 已开启且剪贴板有文本;
  2. extractClipboardPastedText 识别出真实的粘贴增量,且其长度 严格大于 阈值 longPastedTextFileThreshold;
  3. 当前存在有效的聊天会话(currentChatId 非空)。

值得注意的实现细节是草稿保留策略:当识别为超长粘贴时,并不立即提交文本变更,而是先异步创建附件。只有当 attachPastedText 返回 false(I/O 失败)时才回退为 commitUserMessageChange(value),将文本留在输入框——这样即使写入失败也不会丢失用户粘贴的内容。附件创建成功后该次粘贴产生的输入内容即被清空,输入框不会承载超长文本,符合设计文档"输入框不会承载该文本"的预期。

附件创建:清理目录中的 UTF-8 临时文件

ChatViewModel.attachPastedText 负责包装状态与委托调用(ChatViewModel.kt):先为当前聊天设置 InputProcessingState.Processing 状态(文案为"正在处理附件"),调用 attachmentDelegate.attachPastedText(text),无论成败都在 finally 中恢复 Idle。

真正的落盘逻辑在 AttachmentDelegate.attachPastedText(AttachmentDelegate.kt):

  1. 获取 OperitPaths.cleanOnExitDir() 作为存放目录,目录不存在时创建;
  2. 确保目录中存在 .nomedia 文件,避免生成的文本文件出现在系统媒体库中;
  3. 使用 File.createTempFile("pasted_text_", ".txt", externalDir) 创建唯一命名的 .txt 临时文件;
  4. 以 UTF-8 编码写入完整粘贴文本:textFile.writeText(text, Charsets.UTF_8);
  5. 构造 AttachmentInfo(filePath, fileName, mimeType = "text/plain", fileSize) 并 appendAttachment 加入当前聊天的附件列表,使其出现在附件预览中、可随消息一起发送;
  6. 弹出提示 toast chat_pasted_text_attached("已将粘贴文本作为附件添加:%1$s")。
suspend fun attachPastedText(text: String): Boolean =
    withContext(Dispatchers.IO) {
        try {
            val externalDir = OperitPaths.cleanOnExitDir()
            if (!externalDir.exists()) {
                externalDir.mkdirs()
            }

            val noMediaFile = File(externalDir, ".nomedia")
            if (!noMediaFile.exists()) {
                noMediaFile.createNewFile()
            }

            val textFile = File.createTempFile("pasted_text_", ".txt", externalDir)
            textFile.writeText(text, Charsets.UTF_8)

            val addedAttachment =
                appendAttachment(
                    AttachmentInfo(
                        filePath = textFile.absolutePath,
                        fileName = textFile.name,
                        mimeType = "text/plain",
                        fileSize = textFile.length(),
                    )
                )
            _toastEvent.emit(
                context.getString(R.string.chat_pasted_text_attached, addedAttachment.fileName)
            )
            true
        } catch (e: Exception) {
            AppLogger.e(TAG, "Error creating pasted text attachment", e)
            _toastEvent.emit(context.getString(R.string.attachment_add_failed, e.message ?: ""))
            false
        }
    }

写入在 Dispatchers.IO 线程池执行,避免大文本的文件 I/O 阻塞主线程;失败路径记录日志并返回 false,由上层决定是否回退保留草稿。

清理目录的定位

cleanOnExitDir 位于 Operit 的应用根目录之下(OperitPaths.kt):

fun cleanOnExitDir(): File {
    return ensureDir(File(operitRootDir(), CLEAN_ON_EXIT_DIR_NAME))
}

该目录是 Operit 的"退出即清理"临时目录,同样被截图、临时文件等场景复用(如 AccessibilityUITools、StandardUITools 的截图存放),因此粘贴生成的 .txt 文件不会长期占用存储空间,也无需用户手动清理。

本地化与静态核查

按 02-localization-and-verification.md 的规划,该功能新增的文案全部走 Android 资源文件,并完成中英文(及多语言)覆盖。

新增资源键如下(以中英文为例,另覆盖西班牙语、马来语、罗马尼亚语等,见 values/strings.xml 与 values-en/strings.xml):

资源键 中文 英文
chat_pasted_text_attached 已将粘贴文本作为附件添加:%1$s Pasted text added as an attachment: %1$s
long_pasted_text_to_file 超长粘贴文本转文件 Convert long pasted text to a file
long_pasted_text_to_file_desc 粘贴超过设定字符数的文本时,自动作为文本附件添加 Pasted text longer than the configured limit is added as a text attachment
long_pasted_text_threshold 转换阈值 Conversion limit
long_pasted_text_threshold_desc 粘贴文本超过此字符数时转为文件 Pasted text longer than this number of characters is converted to a file
long_pasted_text_threshold_unit 字符 characters

设置名称、说明与转换提示(toast)均由 stringResource / context.getString 引用这些资源键,因此切换应用语言后会自动展示对应语言的文案。本地化核查还包括对受影响调用点与资源引用的静态检查,确保新增字符串在所有语言资源中成对出现、无缺失引用。

行为边界与预期效果

综合设计文档与源码实现,该功能的最终行为可归纳如下:

  • 未达阈值 / 功能关闭:粘贴文本照常进入输入框,走原有文本编辑与发送路径,与改动前行为一致;
  • 超过阈值:输入框不承载该次粘贴的文本,系统在清理目录生成 pasted_text_*.txt 临时文件(UTF-8、text/plain),附件预览中出现可发送的 .txt 文件,并弹出"已将粘贴文本作为附件添加"提示;
  • 写入失败:附件创建失败时回退提交文本变更,粘贴内容保留在输入框中,不因 I/O 错误丢失;
  • 误判防护:仅当新增区间与剪贴板内容(换行归一化后)完全一致时才触发转换,普通输入与输入法行为不会被误触发;
  • 不涉及的范围:消息协议、已有附件处理流程、手动文件选择均不受影响(见 index.md)。

整个功能从设置持久化(UserPreferencesManager)、设置界面(GlobalDisplaySettingsScreen)、粘贴识别(extractClipboardPastedText + PastedTextAttachmentTest.kt)到附件落地(AttachmentDelegate + OperitPaths)形成了完整闭环,为长文本粘贴场景提供了"自动转文件"的轻量解决方案。

登录后查看全文
Operit