# ACP 单聊 - 消息发送与文件处理 (F-MSG + F-FILE-02)

> 本文档由 PM 从 `prd-acp-scenarios.md` 抽取，保持与源同步。
> 覆盖技术场景：S-MSG-01 ~ S-MSG-12, S-FILE-03

---

## (F-MSG-01) 发送文本消息 [部分实现]

> **实现差距**：消息队列基础功能已实现（入队/编辑/删除/清空/自动发送），但缺少「多条排队消息合并为一条发出」

**用户故事**：作为用户，我希望在输入框中输入文字并发送，能立即看到我的消息出现在对话中，同时 AI 开始回复。

**正常流程**（用户视角）：

1. 用户在输入框中输入文本，点击发送
2. 用户的消息立即出现在对话区域（无需等待 AI 后端连接完成）
3. 会话在列表中的排序位置更新为最新
4. 系统自动完成后台连接（若尚未连接）
5. 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（从工作区目录树引用）**

1. 用户在工作区目录树中右键点击某个文件或目录，选择「Add to Chat」
2. 文件/目录以 `@路径` 形式添加到输入框
3. 发送时系统自动读取文件内容并附加到消息中
4. 也可以手动在输入框中输入 `@文件名` 触发自动补全

**方式二：上传文件**

1. 用户点击上传按钮或拖拽文件到输入框区域
2. 文件显示在输入框附近的预览区域
3. 用户输入消息文本并点击发送
4. 文件随消息一起发送给 AI

**方式三：粘贴板**

1. 用户复制文件内容或截图后，在输入框中粘贴
2. 文本内容直接粘贴为消息文本
3. 图片内容作为附件添加到消息中

**异常情况**：

- 引用的文件不存在：系统将原始 `@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 从一开始就按照正确的规则工作，我无需每次手动说明。

**正常流程**（用户视角）：

1. 用户在新会话中发送第一条消息
2. 系统自动在消息中附加预设的 AI 规则和可用技能信息（用户不可见）
3. AI 基于这些规则开始工作
4. 后续消息不再重复注入规则

**异常情况**：

- 没有可用的规则和技能：消息原样发送，不做任何包装
- 用户使用自定义工作区：系统使用文本注入方式而非目录符号链接方式注入规则

**验收标准**：

- [ ] 新会话首条消息自动注入 AI 规则
- [ ] 仅首条消息注入，后续消息不重复
- [ ] 注入内容对用户不可见
- [ ] 自定义工作区场景下规则仍能正确注入

> 覆盖场景：S-MSG-04, S-MSG-05, S-MSG-06

---

## (F-MSG-04) 隐藏消息与静默消息 [已实现]

**用户故事**：作为系统（定时任务、频道集成等），我需要能够发送不显示在用户界面中的消息给 AI，以便后台自动化任务能够无干扰地运行。

**正常流程**（用户视角）：

1. **静默消息**：系统后台发送的消息完全不在界面中显示，也不记录到消息历史。用户完全无感知。
2. **隐藏消息**：消息存在于历史记录中，但不在对话界面中显示。用于后台自动化场景。

**验收标准**：

- [ ] 静默消息不出现在对话界面
- [ ] 静默消息不记录到消息历史
- [ ] 隐藏消息不出现在对话界面但保留在历史中

> 覆盖场景：S-MSG-08

---

## (F-MSG-06) 输入框历史记录 [已实现]

**用户故事**：作为用户，我希望在输入框中通过上下键浏览历史输入，以便快速复用之前发过的消息内容。

**正常流程**（用户视角）：

1. 焦点在输入框时，用户按 `上` 键 -> 显示上一条历史输入内容
2. 继续按 `上` 键 -> 继续往前翻历史
3. 按 `下` 键 -> 往后翻历史，回到更近的输入
4. 用户可以基于历史内容编辑后直接发送

**验收标准**：

- [ ] 上下键在输入框为空或光标在首/末行时触发历史浏览
- [ ] 历史记录按时间倒序排列
- [ ] 选择历史内容后可编辑再发送

---

## (F-MSG-07) 重试与撤销上一轮对话 [未实现]

> **实现差距**：代码库中无任何 redo/undo 相关实现

**用户故事**：作为用户，我希望能够编辑并重新发送最后一轮对话中的消息（重试），或撤销最后一轮对话回到发送前的状态，以便修正提问或尝试不同的表述。

**前置条件**：最后一个 prompt turn 已结束（AI 已完成回复）

**正常流程**（用户视角）：

1. **重试（Redo）**：用户点击最后一条用户消息的「重试」按钮 -> 该消息内容回到输入框供编辑 -> 编辑后重新发送 -> AI 基于编辑后的内容重新回复
2. **撤销（Undo）**：用户点击「撤销」-> 最后一轮对话（用户消息 + AI 回复）从对话历史中移除 -> 回到上一轮对话的状态

**异常情况**：

- 对话历史为空：重试和撤销按钮不可用
- AI 正在回复中：重试和撤销按钮不可用，需等待当前 turn 结束

**不同 AI 后端的差异**：

- 此功能可能依赖 ACP 协议和 Agent 后端是否支持会话历史回滚。不支持的后端可能无法实现撤销功能，仅支持重试（重新发送编辑后的消息）

**验收标准**：

- [ ] 最后一轮用户消息可编辑后重新发送
- [ ] 撤销操作移除最后一轮对话（用户消息 + AI 回复）
- [ ] AI 回复中时重试/撤销不可用
- [ ] 后端不支持回滚时，撤销按钮不显示或提示不支持

---

## (F-MSG-08) `/btw` 追加上下文 [部分实现]

> **实现差距**：/btw 已实现但采用 fork session 独立回答方式，非注入当前 AI 上下文；不支持的后端直接提示不支持而非入队

**用户故事**：作为用户，我希望在 AI 回复过程中通过 `/btw` 命令追加补充信息，AI 能在不中断当前回复的情况下参考这些补充内容。

**前置条件**：AI 正在回复中

**正常流程**（用户视角）：

1. AI 正在回复
2. 用户输入 `/btw 补充内容` 并发送
3. 补充信息被注入到 AI 的当前上下文中
4. AI 在后续回复中参考这些补充内容（不会重新开始回复）

**不同 AI 后端的差异**：

- 目前仅 Claude 后端支持此功能
- 其他后端：`/btw` 消息进入等待队列，等当前 turn 结束后作为普通消息发出

**验收标准**：

- [ ] Claude 后端下 `/btw` 消息实时注入到 AI 上下文
- [ ] 不支持的后端下 `/btw` 消息进入等待队列
- [ ] `/btw` 消息在对话界面中有区别于普通消息的展示

---

## (F-FILE-02) AI 读取和写入文件 [已实现]

> **实现差距**：V2 路径缺少 auto-mkdir 和编辑器通知，但当前走 V1 路径，V1 完整实现

**用户故事**：作为用户，我希望 AI 能够按需读取我工作区中的文件、以及在工作区中创建或修改文件，以便 AI 可以帮我完成代码编写、文档编辑等任务。

**前置条件**：用户已设置工作区目录

**正常流程**（用户视角）：

1. 用户在对话中要求 AI 读取某个文件或修改某个文件
2. AI 自动执行文件读取或写入操作
3. 对话中显示 AI 执行的文件操作记录（读取了哪个文件、编辑了哪个文件）
4. 如果是写入操作，用户可以在编辑器中看到文件内容的实时更新

**异常情况**：

- 读取不存在的文件：AI 收到错误信息并在对话中告知用户
- 写入时目标目录不存在：系统自动创建所需目录

**验收标准**：

- [ ] AI 能读取工作区内的文本文件
- [ ] AI 能在工作区内创建新文件或修改现有文件
- [ ] 文件操作以工具调用的形式展示在对话中
- [ ] 写入时自动创建不存在的目录
- [ ] 文件写入后编辑器实时收到内容更新通知

> 覆盖场景：S-FILE-03