---
url: /wave-agent/specs/ui/bash-mode.md
description: '`!` 前缀在聊天输入直接执行 shell 命令，输出以 bash tool block 全量展示并进入模型上下文，命令可中止'
---

# 功能规格说明：Bash 模式

**创建日期**：2026-03-25

**最近更新**：2026-08-26（改名 Bang → Bash 模式；输出统一为 user 消息 bash tool block 承载，执行复用 bash 工具）

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

### 用户故事：基本命令执行（优先级：P1）

作为用户，我希望能够通过 `!` 前缀直接从聊天输入执行 shell 命令，以便我可以快速执行系统操作而无需离开 agent 界面。

**为什么是这个优先级**：这是功能的核心。它为用户提供了与系统交互的强大方式。

**独立测试**：可以通过在聊天输入中输入 `!echo "hello"` 等命令并验证命令被执行且输出 "hello" 显示在对话中来测试。

**验收场景**：

1. **假设**聊天输入为空，**当**用户输入 `!ls -la` 并按下 Enter 时，**则**命令 `ls -la` 在当前工作目录中执行，对话中出现一条 user 消息（内容为 `ls -la`），其下以 bash tool block 形态显示命令输出。
2. **假设**命令正在执行中，**当**用户输入另一个命令时，**则**系统应该防止并发执行并显示错误消息。

***

### 用户故事：输出全量展示（优先级：P2）

作为用户，我希望 shell 命令的输出完整显示在对话中，以便我可以随时回溯查看完整结果。

**为什么是这个优先级**：bash 模式输出作为 user 消息 tool block 承载，复用 bash 工具块渲染规则——result 全量展示不截断。原始 bang spec 的「20 行只显示最后 3 行」截断规则因渲染统一而移除。

**独立测试**：可以通过执行具有多行输出的命令（如 `!seq 1 100`）并验证全部 100 行都显示在消息流中来测试。

**验收场景**：

1. **假设**一个 20 行输出的命令，**当**输出显示在消息流中时，**则**全部 20 行完整展示，不截断、不折叠。

***

### 用户故事：命令中止（优先级：P2）

作为用户，我希望能够中止长时间运行的 shell 命令，如果我意识到这是一个错误或它花费太长时间。

**为什么是这个优先级**：这防止 agent 卡在等待可能永远不会完成或用户不再想运行的命令上。

**验收场景**：

1. **假设**长时间运行的命令如 `!sleep 60` 正在执行，**当**用户触发中止操作（如 Ctrl+C）时，**则**进程被杀死，命令输出条目反映命令已终止（如 result 标注退出码 130）。

***

### 边界情况

* **命令不存在怎么办？** 系统应该捕获 shell 的错误并在命令输出条目中显示，带有错误状态（如 `[exit code: 127]`）。
* **命令没有产生输出怎么办？** 命令输出条目仍应显示命令，但输出区域应为空或隐藏。
* **命令被信号中断（如 SIGINT）怎么办？** 系统应该优雅地处理信号，在 result 中标注退出码（如 130），并显示命令已被中断。
* **命令在不存在的目录中执行怎么办？** 执行层应该处理错误并向用户报告。

***

## 实现说明（开发者视角，非验收行为）

* **消息承载**：bash 模式消息不再使用独立 `BangBlock` 块类型，改为 user 消息 + bash tool block（`name: "Bash"`（`BASH_TOOL_NAME`），parameters 存命令，result 存输出）。消息文本块忠实回显命令本身。
* **执行复用**：bash 模式执行复用 bash 工具执行引擎（shell 解析、CWD 追踪、超时、输出处理），不再维护独立 spawn 逻辑。运行期间**不**写 tool block，输出只在命令结束时一次性写入（见 [Bash 工具](../core/bash-tools.md) 的「输出在命令结束时一次性下发」）。
* **输出进上下文**：user 消息 tool block 的 result 经 `<local-command-stdout>` 规则进入模型上下文（convertMessagesForAPI 通用逻辑）；不触发 AI 回复。
* **退出码呈现**：成功（exit 0）不标注；失败在 result 文本前缀标注 `[exit code: N]`。
* **中止**：复用 bash 工具的 abort 机制（AbortSignal，SIGINT 退出码 130）。
* **回滚检查点**：bash 模式命令消息是用户真实输入，与 fork 技能命令消息一致，可作为 /rewind 检查点（系统生成的输出块不作为检查点依据）。