---
url: /wave-agent/specs/commands/clear-command.md
description: '`/clear` 命令清空对话历史并生成新会话 ID，SDK 侧对应 `agent.clearMessages()`'
---

# 功能规格说明：清除命令

**创建日期**：2026-04-01

## 用户场景与测试 *（必填）*

### 用户故事：通过斜杠命令清除对话（优先级：P1）

作为 CLI 用户，我希望输入 `/clear` 来重置对话历史，以便在不重启应用的情况下开始全新会话。

**验收场景**：

1. **假设** 存在一个活跃对话且有消息，**当** 用户输入 `/clear`，**则** 对话历史被清除，生成新的会话 ID，并清除终端屏幕。
2. **假设** CLI 中已有一段包含多条消息的对话，**当** `/clear` 清空完成，**则** 可见屏幕被完全清空：旧的消息列表不得残留在屏幕上（无论清空过程中是否有其他 UI 状态更新打断渲染），屏幕仅显示欢迎头部与输入框，与 Ctrl+O 展开再收起后的视图一致。
3. **假设** 清空前的那段对话已经渲染过，**当** `/clear` 清空完成，**则** 它仍然留在终端滚动缓冲里，向上翻可以看回来——`/clear` 只擦掉自己画的那一屏，不连终端历史一起抹掉（对齐「新对话」而非「销毁证据」的语义）。
4. **假设** 清空是靠「重挂载消息列表，让 append-only 的 `<Static>` 从头重渲染」实现的，**当** 走的是 `/clear`，**则** 先用 ink 实例的 `clear()` 重置行记账再重挂载；其它同样需要重渲染的结构性动作（切换会话、回退、Ctrl+O 展开/收起）**仍然**连滚动缓冲一起擦除，因为那些动作会让新旧两份内容同时留在屏幕上。
5. **假设** 正在处理中的 AI 响应，**当** 用户输入 `/clear`，**则** `/clear` 被忽略：AI 处理不被中止，对话历史保持不变（与插件端一致）；AI 空闲时 `/clear` 才清除对话并生成新的会话 ID。
6. **假设** 任务列表包含当前会话的项目，**当** `/clear` 执行后，**则** 任务列表与新的会话 ID 同步。

***

### 用户故事：通过 SDK 程序化清除（优先级：P1）

作为 SDK 消费者，我希望调用 `agent.clearMessages()` 来重置对话，以便我的应用程序可以程序化地开始新会话。

**验收场景**：

1. **假设** 存在一个活跃的代理会话且有消息，**当** 调用 `agent.clearMessages()`，**则** 对话历史被清除并生成新的会话 ID，效果与输入 `/clear` 相同。

***

### 边界情况

* **如果在没有对话的情况下调用 `/clear` 会发生什么？** 仍然会生成新的会话 ID；不会抛出错误。
* **桌面端 `/clear` 支持情况**：桌面端 `/clear` 命令已于 2026-09-05 整端移除——`/clear` 不再出现在斜杠命令列表中，手动输入 `/clear` 会作为普通消息发送（SDK 从未注册 clear，消息直接交给模型，无害）。"新对话"入口保留在侧边栏，生成全新的代理会话。