# CLI UI 显示规范（草案）

> 目标：把 Web 端已有的信息表达方式，压缩成一个低噪声、可扫描、适合终端的 CLI 交互层。
> 适用范围：CLI 前端展示层，不定义 Agent Runtime 本身。

## 1. 设计原则

1. **事件流优先**：CLI 只消费结构化事件，不直接消费原始 API 响应。
2. **极简优先**：正文少、状态清楚、动作明确。
3. **固定符号**：统一用少量状态符号表达进度与结果。
4. **完整展示变更**：文件编辑类内容不折叠，直接完整显示。
5. **思考可见但不冗长**：只保留滚动中的短窗口，不保留完整历史。
6. **交互独立**：审批、选择、Slash 命令都走独立输入态。

---

## 2. 总体布局

```text
[历史事件区]
[当前思考 / 工具 / 子智能体输出]
[最终结果]
──
[输入栏]
[状态栏]
```

### 底部状态栏建议

```text
5 后台智能体  3 后台指令  版本控制: 开  自动审批  沙箱  24k/200k
```

可扩展字段：

- 模型名
- 运行模式（thinking / fast 先不做切换也可保留显示位）
- Git 开关
- 自动审批状态
- 沙箱/直连状态
- 上下文剩余量

---

## 3. 状态符号

| 状态 | 符号 | 颜色 | 说明 |
|---|---|---|---|
| 运行中 | `◦` / `•` 交替 | 黄/灰 | 闪烁 |
| 完成 | `•` | 绿 | 静态 |
| 失败 | `•` | 红 | 静态 |
| 用户输入 | `›` | 白/青 | 静态 |
| 审批中 | `◦` | 黄 | 慢闪 |
| 已取消 | `•` | 灰 | 静态 |

---

## 4. 思考块显示

思考块只保留一种样式：**5 行滚动窗口**。

### 4.1 运行中

```text
◦ 思考中
  └ 第一行
    第二行
    第三行
    第四行
    第五行
```

当加入第 6 行时，自动滚动：

```text
◦ 思考中
  └ 第二行
    第三行
    第四行
    第五行
    第六行
```

### 4.2 完成后

```text
• 思考完成 4.2s
```

不做折叠展开，不保留完整思考历史。

### 4.3 规则

- 只显示最新 5 行
- 只显示当前思考内容
- 完成后只留完成状态
- 不显示“思考全文”

---

## 5. 子智能体前台显示

子智能体前台展示方式与思考块一致，也是 5 行滚动窗口。

```text
◦ 子智能体 review-agent...
  └ 运行 ls -la && pwd
    搜索 python 新版本
    第三行
    第四行
    第五行
```

完成后：

```text
• 子智能体完成 8.1s
```

### 规则

- 子智能体只显示前台进度，不显示全部历史
- 只保留最新 5 行
- 完成态只显示耗时和结果摘要

---

## 6. 工具块通用格式

统一使用：

```text
• 动作摘要
  └ 结果摘要
```

### 6.1 运行中

```text
◦ 运行 npm run build
  └ 正在执行...
```

### 6.2 完成

```text
• 运行 npm run build
  └ 成功，用时 8.2s
```

### 6.3 失败

```text
• 运行 npm run build
  └ 失败，exit code 2
```

---

## 7. 工具显示规范

下面定义 `└` 后面的内容包含哪些字段、如何显示。

### 7.1 运行命令类

#### 适用工具

- `run_command`
- `terminal_input`
- `terminal_session`
- `terminal_snapshot`

#### 显示字段

- `command` / `input`
- `timeout`
- `exit_code`
- `stdout` / `output`
- `stderr`（若可分离）

#### 显示规则

```text
• 运行 printf '' > test.txt && ls -l test.txt
  └ -rw-r--r--  1 jojo  staff  0 May 14 14:48 test.txt
```

长输出：

```text
• 运行 ls -la && pwd
  └ 第 1 行内容
    第 2 行内容
    … +6 lines
    第 9 行内容
    第 10 行内容
```

#### 约束

- 第一行优先显示结果中最有信息量的一行
- 长文本可局部截断，但不要丢掉关键错误
- 如果有 exit code，必须显示

---

### 7.2 文件编辑类

#### 适用工具

- `write_file`
- `edit_file`

#### 原则

**必须完整显示，不折叠。**

因为：

- 这是文件内容本身，不是工具摘要
- 单次替换通常不会太大
- 终端里保留完整 + / - 最有价值

#### 7.2.1 Write

显示字段：

- `path`
- `mode`（append / overwrite）
- `status`
- `content`

显示模板：

```text
• Write test.txt (+3 -0)
    1 +这是第一行测试内容。
    2 +这是第二行测试内容。
    3 +这是第三行测试内容。
```

#### 7.2.2 Edit

显示字段：

- `path`
- `replace_all`
- `found`
- `replacements`
- 每个 replacement 的 `old` / `new`

显示模板：

```text
• Edited main.py (+2 -2)
    14 -old line 1
    15 -old line 2
    14 +new line 1
    15 +new line 2
```

#### 7.2.3 规则

- 不折叠
- 不显示上下文行
- 只显示参数里已有的变更信息
- 若存在多段替换，按替换顺序逐段输出

---

### 7.3 阅读类

#### 适用工具

- `read_file`
- `read_skill`

#### 显示字段

- `path`
- `status`
- `size`
- `read_type`
- `content`
- `search` / `extract` 子模式信息

#### 显示模板

普通读取：

```text
• 阅读 test.txt
  └ 读取 3 行
```

提取模式：

```text
• 阅读 test.txt
  └ 提取第 12-28 行
```

搜索模式（如果未来恢复）：

```text
• 搜索 handle_task
  └ 找到 12 处，位于 5 个文件
```

#### 规则

- 正文尽量压缩成“读取了多少 / 提取了什么 / 找到了什么”
- 需要看全文时再走展开命令

---

### 7.4 搜索类

当前 CLI v1 **不做搜索工具**。

如果未来恢复，显示方式参考阅读类：

```text
• 搜索 "xxx"
  └ 找到 N 处，位于 M 个文件
```

---

### 7.5 文件创建 / 删除 / 重命名

当前 CLI v1 **不做这些工具块**，可直接忽略。

---

### 7.6 子智能体 / 后台任务类

#### 显示字段

- `name`
- `status`
- `latest_progress_lines`
- `elapsed`

#### 显示模板

```text
◦ 子智能体 review-agent...
  └ 运行 ls -la && pwd
    搜索 python 新版本
    第三行
    第四行
    第五行
```

完成后：

```text
• 子智能体完成 8.1s
```

#### 规则

- 只显示最新 5 行
- 运行中用 `◦`
- 完成后用 `•`

---

### 7.7 审批 / 交互类

#### 适用场景

- 权限审批
- 需要用户确认的危险操作
- 自定义选择
- Slash 命令补全

#### 显示方式

使用**输入栏扩展 + 选项列表**，不是普通消息流。

示例：

```text
┌────────────────────────────────────┐
│ 需要批准：运行 rm -rf dist         │
│ 原因：删除构建目录                 │
│                                    │
│ › 1. Allow once                    │
│   2. Always allow                  │
│   3. Deny                          │
└────────────────────────────────────┘
```

#### 规则

- 上下键切换
- 当前行高亮
- Enter 确认
- Esc 或拒绝关闭

---

## 8. Slash 命令规范

所有操作都通过 `/` 输入。

### 8.1 触发方式

输入 `/` 或 `/a` 后，打开命令建议列表。

### 8.2 显示方式

```text
› /approve   简要说明
  /allow     简要说明
  /assist    简要说明
```

### 8.3 规则

- 支持模糊过滤
- 上下键选择
- 当前项变色
- Enter 执行

---

## 9. 最终输出区

任务完成后，使用固定分隔结构：

```text
──

• 已创建 test.txt 文件。

  1. 修改文件列表：test.txt
  2. 核心变更点：在 /Users/jojo/Desktop/test 下创建了一个空文本文件
  3. 验证结果：已执行 ls -l test.txt，文件存在。

──
```

### 最终结果字段

建议统一输出：

1. **修改文件列表**
2. **核心变更点**
3. **验证结果**

如果有失败：

- 失败原因
- 已做的尝试
- 下一步建议

---

## 10. 信息优先级

从高到低：

1. 当前交互态（审批 / 命令选择）
2. 当前思考 / 当前子智能体进度
3. 当前工具输出
4. 最终结论
5. 低优先级元信息

---

## 11. 参考的 Web 端表现

Web 端已经存在的对应参考：

- `static/src/components/chat/actions/ThinkingAction.vue`
  - 思考块
  - 运行中 / 完成两态
  - 可折叠
- `static/src/components/chat/actions/ToolAction.vue`
  - 工具块
  - `renderEnhancedToolResult()`
  - 文件编辑 / 读取 / 命令 / 图片等不同分支
- `static/src/components/chat/StackedBlocks.vue`
  - 思考 + 工具的堆叠展示
- `static/src/components/chat/MinimalBlocks.vue`
  - 摘要组展示
  - 最终只保留当前步骤预览
- `static/src/components/panels/ToolApprovalPanel.vue`
  - 审批面板
  - 编辑 diff、写入内容、命令预览

CLI 的目标不是复制这些视觉细节，而是抽取其中最有信息价值的字段。

---

## 12. 推荐的 CLI 默认策略

### 默认开启

- 5 行思考滚动
- 5 行子智能体滚动
- 文件编辑完整展示
- 命令输出摘要展示
- Slash 命令补全
- 审批选择弹层

### 默认关闭

- 完整思考历史
- 文件创建 / 删除 / 重命名显示
- 搜索工具
- 折叠展开复杂交互

---

## 13. 一句话总结

CLI 的目标是：

> 用最少的符号，表达最多的有效信息；用固定的状态和结构，让用户能一眼看懂 Agent 在做什么。
