---
url: /wave-agent/specs/ui/markdown-rendering-system.md
description: 终端 Markdown 渲染，Ink 组件支持标题、列表、代码块、表格
---

# 功能规格说明：Markdown 渲染系统

**创建日期**：2024-12-01\
**更新日期**：2026-08-04

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

### 用户故事：富文本显示（优先级：P1）

作为用户，我希望看到代理响应以标题、粗体文本和列表格式化，以便信息在终端中易于阅读和浏览。

**为什么是这个优先级**：对代理响应的可读性至关重要，代理响应通常包含结构化信息。

**独立测试**：可以向 `Markdown` 组件提供包含标题、粗体、斜体和列表的 markdown 字符串，并验证它们以适当的强调样式（粗体、斜体、缩进）渲染。

**验收场景**：

1. **假设**markdown 字符串包含 `# Heading`，**当**渲染时，**则**它以粗体青色出现并带 `#` 前缀
2. **假设**markdown 字符串包含 `**bold**` 和 `*italic*`，**当**渲染时，**则**它们分别以粗体和斜体样式出现
3. **假设**markdown 字符串包含无序或有序列表，**当**渲染时，**则**它以适当的缩进和项目符号/编号出现

***

### 用户故事：代码块渲染（优先级：P1）

作为开发者，我希望看到代码块与常规文本清晰分离，支持语言提示和适当的间距。

**为什么是这个优先级**：Wave Agent 频繁生成和显示代码，因此清晰的代码块渲染至关重要。

**独立测试**：可以向 `Markdown` 组件提供包含带语言提示的围栏代码块的 markdown 字符串，并验证它被渲染为围栏包围的独立块。

**验收场景**：

1. **假设**带语言提示的围栏代码块，**当**渲染时，**则**开头和结尾的围栏反引号被显式呈现（不被省略），块内容与正文分离
2. **假设**没有语言提示的代码块，**当**渲染时，**则**它以简单文本块显示

***

### 用户故事：响应式表格渲染（优先级：P2）

作为用户，我希望看到数据表格在终端中以单线 box-drawing 边框渲染，列宽根据内容与终端宽度自适应，以便我可以查看结构化数据而不破坏布局。

**为什么是这个优先级**：表格是展示结构化数据的常见方式，而终端宽度是一个重要约束。

**独立测试**：可以向 `Markdown` 组件提供包含不同内容长度、对齐指令（`:---` / `:---:` / `---:`）和中文内容的 markdown 表格，并验证它以单线边框渲染、表头居中、数据按对齐指令对齐、列宽适应终端宽度。

**验收场景**：

1. **假设** markdown 表格被渲染，**则** 它以单线 box-drawing 边框（`┌─┬┐` / `├─┼┤` / `└─┴┘`）出现，表头居中对齐，数据列默认左对齐
2. **假设** 表格列带对齐指令（`:---:` 居中对齐、`---:` 右对齐），**当**渲染时，**则** 数据单元格按指令对齐
3. **假设** 表格内容总宽度未超过终端可用宽度，**当**渲染时，**则** 列宽取内容理想宽度
4. **假设** 表格超出终端可用宽度但未超过各列最小宽度之和，**当**渲染时，**则** 列宽按超出比例缩小以适应可用空间
5. **假设** 表格远超终端宽度，**当**渲染时，**则** 单元格内容换行而非截断，列宽按最小值等比缩小
6. **假设** 某行换行后行高超过 4 行，或表格渲染行仍超宽，**当**渲染时，**则** 表格转为纵向键值对格式（加粗标签 + 分隔线 + 缩进续行），避免列过窄或终端闪烁
7. **假设** 单元格含中文等宽字符，**当**渲染时，**则** 按显示宽度对齐（中文按 2 列宽计算），不因字符编码宽度错位

***