wehub-resource-sync
11 KiB
ACP 单聊 - 消息发送与文件处理 (F-MSG + F-FILE-02)
本文档由 PM 从
prd-acp-scenarios.md抽取，保持与源同步。 覆盖技术场景：S-MSG-01 ~ S-MSG-12, S-FILE-03
(F-MSG-01) 发送文本消息 [部分实现]
实现差距：消息队列基础功能已实现（入队/编辑/删除/清空/自动发送），但缺少「多条排队消息合并为一条发出」
用户故事：作为用户，我希望在输入框中输入文字并发送，能立即看到我的消息出现在对话中，同时 AI 开始回复。
正常流程（用户视角）：
- 用户在输入框中输入文本，点击发送
- 用户的消息立即出现在对话区域（无需等待 AI 后端连接完成）
- 会话在列表中的排序位置更新为最新
- 系统自动完成后台连接（若尚未连接）
- AI 开始流式输出回复内容
AI 回复期间的消息队列：
- AI 正在回复时，输入框仍可输入。用户发送的消息进入等待队列
- 队列中的消息可以逐条编辑或删除，也支持一键清空队列
- 当前 turn 结束后，队列中的消息自动发出
- 如果队列中有多条消息，系统在等待期间将其合并为一条发出
异常情况：
- 未输入任何内容点击发送：系统不响应
- AI 后端连接失败：用户的消息已显示在对话中，系统显示错误提示，告知连接失败原因并建议操作
- AI 回复过程中发生错误：系统显示错误消息，随后恢复输入框为可用状态
- 会话不存在或已被删除：系统提示「会话未找到」
不同 AI 后端的差异：
- Qwen：若出现内部错误，系统会提供增强的错误提示信息
验收标准：
- 用户消息立即显示，不等待后端连接
- 会话列表排序实时更新
- AI 连接失败时显示明确的错误提示
- 错误发生后界面恢复可用状态（不卡在加载中）
- 已缓冲的部分 AI 回复在发生错误时不丢失
- AI 回复期间可继续输入并发送消息到队列
- 队列中的消息可编辑、删除、一键清空
- 当前 turn 结束后队列消息自动发出
- 多条队列消息在等待期间合并为一条发出
覆盖场景：S-MSG-01, S-MSG-02, S-MSG-09, S-MSG-10, S-MSG-11, S-MSG-12
(F-MSG-02) 在消息中引用文件 [部分实现]
实现差距：三种引用方式均已实现，但缺少：(1) 多方式引用同一文件时自动去重；(2) 路径标记剥离不完整
用户故事：作为用户，我希望能以多种方式将文件内容提供给 AI，以便 AI 能基于这些文件进行回复。
前置条件：用户已设置工作区目录（Add to Chat 方式需要）
文件引用的三种方式：
方式一：Add to Chat（从工作区目录树引用）
- 用户在工作区目录树中右键点击某个文件或目录，选择「Add to Chat」
- 文件/目录以
@路径形式添加到输入框 - 发送时系统自动读取文件内容并附加到消息中
- 也可以手动在输入框中输入
@文件名触发自动补全
方式二：上传文件
- 用户点击上传按钮或拖拽文件到输入框区域
- 文件显示在输入框附近的预览区域
- 用户输入消息文本并点击发送
- 文件随消息一起发送给 AI
方式三：粘贴板
- 用户复制文件内容或截图后，在输入框中粘贴
- 文本内容直接粘贴为消息文本
- 图片内容作为附件添加到消息中
异常情况：
- 引用的文件不存在：系统将原始
@filename文本直接传递给 AI，由 AI 自行处理 - 引用的是二进制文件（如图片、编译产物）：系统不内联读取内容，而是将文件引用传递给 AI 后端处理
- 同时通过多种方式引用了同一文件：系统自动去重
不同 AI 后端的差异：
- Gemini：上传的文件会被临时复制到工作区目录中，AI 完成回复后临时文件自动清理
- 其他后端：文件通过路径引用或内容内联的方式传递
验收标准：
- Add to Chat 方式：从目录树选择文件/目录后以
@路径添加到输入框 - 上传方式：支持拖拽和按钮上传
- 粘贴板方式：支持粘贴文本和图片
- 文件内容被附加到消息中供 AI 参考
- 二进制文件不做内联读取
- 多种方式引用同一文件时自动去重
- 附件路径以工作区相对路径形式展示，工作区外的文件仅显示文件名
- AI 收到的消息不包含界面展示用的路径标记
- 上传失败不阻塞消息发送
- Gemini 后端下上传文件自动复制到工作区，回复后自动清理；用户可配置是否保留
覆盖场景：S-MSG-03, S-MSG-07, S-FILE-01, S-FILE-02, S-FILE-04
(F-MSG-03) 首条消息自动注入 AI 规则 [已实现]
用户故事：作为用户，我希望每个新会话的第一条消息自动包含 AI 的行为规则和技能索引，以便 AI 从一开始就按照正确的规则工作，我无需每次手动说明。
正常流程（用户视角）：
- 用户在新会话中发送第一条消息
- 系统自动在消息中附加预设的 AI 规则和可用技能信息（用户不可见）
- AI 基于这些规则开始工作
- 后续消息不再重复注入规则
异常情况：
- 没有可用的规则和技能：消息原样发送，不做任何包装
- 用户使用自定义工作区：系统使用文本注入方式而非目录符号链接方式注入规则
验收标准：
- 新会话首条消息自动注入 AI 规则
- 仅首条消息注入，后续消息不重复
- 注入内容对用户不可见
- 自定义工作区场景下规则仍能正确注入
覆盖场景：S-MSG-04, S-MSG-05, S-MSG-06
(F-MSG-04) 隐藏消息与静默消息 [已实现]
用户故事：作为系统（定时任务、频道集成等），我需要能够发送不显示在用户界面中的消息给 AI，以便后台自动化任务能够无干扰地运行。
正常流程（用户视角）：
- 静默消息：系统后台发送的消息完全不在界面中显示，也不记录到消息历史。用户完全无感知。
- 隐藏消息：消息存在于历史记录中，但不在对话界面中显示。用于后台自动化场景。
验收标准：
- 静默消息不出现在对话界面
- 静默消息不记录到消息历史
- 隐藏消息不出现在对话界面但保留在历史中
覆盖场景：S-MSG-08
(F-MSG-06) 输入框历史记录 [已实现]
用户故事：作为用户，我希望在输入框中通过上下键浏览历史输入，以便快速复用之前发过的消息内容。
正常流程（用户视角）：
- 焦点在输入框时，用户按
上键 -> 显示上一条历史输入内容 - 继续按
上键 -> 继续往前翻历史 - 按
下键 -> 往后翻历史，回到更近的输入 - 用户可以基于历史内容编辑后直接发送
验收标准：
- 上下键在输入框为空或光标在首/末行时触发历史浏览
- 历史记录按时间倒序排列
- 选择历史内容后可编辑再发送
(F-MSG-07) 重试与撤销上一轮对话 [未实现]
实现差距：代码库中无任何 redo/undo 相关实现
用户故事：作为用户，我希望能够编辑并重新发送最后一轮对话中的消息（重试），或撤销最后一轮对话回到发送前的状态，以便修正提问或尝试不同的表述。
前置条件：最后一个 prompt turn 已结束（AI 已完成回复）
正常流程（用户视角）：
- 重试（Redo）：用户点击最后一条用户消息的「重试」按钮 -> 该消息内容回到输入框供编辑 -> 编辑后重新发送 -> AI 基于编辑后的内容重新回复
- 撤销（Undo）：用户点击「撤销」-> 最后一轮对话（用户消息 + AI 回复）从对话历史中移除 -> 回到上一轮对话的状态
异常情况：
- 对话历史为空：重试和撤销按钮不可用
- AI 正在回复中：重试和撤销按钮不可用，需等待当前 turn 结束
不同 AI 后端的差异：
- 此功能可能依赖 ACP 协议和 Agent 后端是否支持会话历史回滚。不支持的后端可能无法实现撤销功能，仅支持重试（重新发送编辑后的消息）
验收标准：
- 最后一轮用户消息可编辑后重新发送
- 撤销操作移除最后一轮对话（用户消息 + AI 回复）
- AI 回复中时重试/撤销不可用
- 后端不支持回滚时，撤销按钮不显示或提示不支持
(F-MSG-08) /btw 追加上下文 [部分实现]
实现差距：/btw 已实现但采用 fork session 独立回答方式，非注入当前 AI 上下文；不支持的后端直接提示不支持而非入队
用户故事：作为用户，我希望在 AI 回复过程中通过 /btw 命令追加补充信息，AI 能在不中断当前回复的情况下参考这些补充内容。
前置条件：AI 正在回复中
正常流程（用户视角）：
- AI 正在回复
- 用户输入
/btw 补充内容并发送 - 补充信息被注入到 AI 的当前上下文中
- AI 在后续回复中参考这些补充内容（不会重新开始回复）
不同 AI 后端的差异：
- 目前仅 Claude 后端支持此功能
- 其他后端：
/btw消息进入等待队列，等当前 turn 结束后作为普通消息发出
验收标准：
- Claude 后端下
/btw消息实时注入到 AI 上下文 - 不支持的后端下
/btw消息进入等待队列 /btw消息在对话界面中有区别于普通消息的展示
(F-FILE-02) AI 读取和写入文件 [已实现]
实现差距：V2 路径缺少 auto-mkdir 和编辑器通知，但当前走 V1 路径，V1 完整实现
用户故事：作为用户，我希望 AI 能够按需读取我工作区中的文件、以及在工作区中创建或修改文件，以便 AI 可以帮我完成代码编写、文档编辑等任务。
前置条件：用户已设置工作区目录
正常流程（用户视角）：
- 用户在对话中要求 AI 读取某个文件或修改某个文件
- AI 自动执行文件读取或写入操作
- 对话中显示 AI 执行的文件操作记录（读取了哪个文件、编辑了哪个文件）
- 如果是写入操作，用户可以在编辑器中看到文件内容的实时更新
异常情况：
- 读取不存在的文件：AI 收到错误信息并在对话中告知用户
- 写入时目标目录不存在：系统自动创建所需目录
验收标准：
- AI 能读取工作区内的文本文件
- AI 能在工作区内创建新文件或修改现有文件
- 文件操作以工具调用的形式展示在对话中
- 写入时自动创建不存在的目录
- 文件写入后编辑器实时收到内容更新通知
覆盖场景：S-FILE-03