Skill: cn-big-cabbage/rich (version 0.1.0)

--- name: rich description: Rich - Python 终端富文本和美化格式库 version: 0.1.0 metadata: openclaw: requires: - rich emoji: 🎨 homepage: https://rich.readthedocs.io --- # Rich - Python 终端富文本和美化格式库 ## 技能概述 本技能帮助用户使用 Rich 在 Python 终端程序中输出美观的富文本内容，支持以下场景： - **彩色输出**: 使用标记语法为文本添加颜色、样式和表情符号 - **表格渲染**: 创建美观的 ASCII 表格，支持多种边框样式 - **进度条**: 显示任务进度、下载进度、批量操作进度 - **Markdown 渲染**: 在终端中渲染 Markdown 文本 - **语法高亮**: 对代码片段进行语法高亮显示 - **结构化日志**: 替换标准 logging，输出格式化日志 - **Python 对象美化打印**: 替代 pprint，输出带颜色和折叠的对象 **GitHub**: https://github.com/Textualize/rich（56k+ Stars） ## 使用流程 AI 助手将引导你完成以下步骤： 1. 安装 Rich（如未安装） 2. 选择合适的组件（Console、Table、Progress 等） 3. 编写代码并查看效果 4. 根据需求调整样式和配置 ## 关键章节导航 - [安装指南](./guides/01-installation.md) - [快速开始](./guides/02-quickstart.md) - [高级用法](./guides/03-advanced-usage.md) - [常见问题](./troubleshooting.md) ## AI 助手能力 当你向 AI 描述终端输出需求时，AI 会： - 自动生成对应的 Rich 代码片段 - 选择最合适的 Rich 组件（Table/Panel/Progress 等） - 调整颜色、样式等视觉参数 - 集成到现有项目代码中 - 处理不同终端环境的兼容性问题 - 将 print/logging 替换为 Rich 输出 ## 核心功能 - 支持 Console 对象统一管理终端输出 - 支持标记语法（Markup）设置文本样式 - 支持 16/256/True Color 颜色模式 - 支持 Table（表格）、Panel（面板）、Tree（树形）等渲染组件 - 支持 Progress（进度条）和 Live（动态刷新） - 支持 Syntax（语法高亮）和 Markdown（文档渲染） - 支持 Traceback（美化异常追踪） - 支持 Inspect（对象检查） - 支持 Logging Handler 集成 - 支持导出 HTML/SVG 终端截图 ## 快速示例 ```python # 最简单的用法 - 使用全局 print from rich import print print("[bold magenta]Hello[/bold magenta], [green]World[/green]! :sparkles:") # 使用 Console 对象 from rich.console import Console console = Console() console.print("[bold]Rich[/bold] is [italic green]awesome[/italic green]!") # 美化打印 Python 对象 from rich import pretty pretty.install() {"name": "rich", "stars": 56000, "features": ["color", "table", "progress"]} ``` ```python # 渲染表格 from rich.console import Console from rich.table import Table console = Console() table = Table(title="Python 包对比") table.add_column("名称", style="cyan", no_wrap=True) table.add_column("Stars", style="magenta") table.add_column("用途", style="green") table.add_row("rich", "56k+", "终端美化") table.add_row("click", "14k+", "命令行解析") table.add_row("typer", "13k+", "CLI 框架") console.print(table) ``` ```python # 进度条 from rich.progress import track for step in track(range(100), description="处理中..."): # 执行任务 pass ``` ## 安装要求 - Python 3.8 或更高版本 - pip 包管理器 - 支持 ANSI 转义码的终端（macOS Terminal、iTerm2、Windows Terminal、Linux 各终端） ## 许可证 MIT License ## 项目链接 - GitHub: https://github.com/Textualize/rich - 官方文档: https://rich.readthedocs.io - PyPI: https://pypi.org/project/rich/ - 示例代码: https://github.com/Textualize/rich/tree/master/examples

path: guides/01-installation.md
content: # 安装指南

**适用场景**: 首次使用 Rich，需要安装和配置环境

---

## 一、安装前准备

### 目标
确保系统具备运行 Rich 的基础环境

### 前置条件
- Python 3.8 或更高版本
- pip 包管理器
- 支持 ANSI 的终端（大多数现代终端均支持）

### 检查 Python 环境

**AI 执行说明**: AI 将自动检查你的 Python 版本

```bash
# 检查 Python 版本
python --version
# 或
python3 --version

# 检查 pip
pip --version
# 或
pip3 --version
```

**期望结果**:
- Python 3.8+ ✅
- pip 已安装 ✅

---

## 二、安装 Rich

### 方法1: 使用 pip 安装（推荐）

**AI 执行说明**: AI 可以直接执行安装命令

```bash
pip install rich
```

**验证安装**:
```bash
python -c "import rich; print(rich.__version__)"
```

**期望结果**:
```
13.9.4
```

### 方法2: 使用 conda 安装

```bash
conda install -c conda-forge rich
```

### 方法3: 从源码安装（最新开发版）

```bash
pip install git+https://github.com/Textualize/rich.git
```

### 方法4: 使用 uv 安装（推荐用于现代项目）

```bash
uv add rich
```

### 方法5: 添加到项目依赖

```bash
# 写入 requirements.txt
echo "rich>=13.0.0" >> requirements.txt
pip install -r requirements.txt
```

或在 `pyproject.toml` 中添加：
```toml
[project]
dependencies = [
    "rich>=13.0.0",
]
```

---

## 三、验证安装

### 运行 Rich 内置演示

**AI 执行说明**: AI 将运行演示命令确认安装成功

```bash
# 运行 Rich 自带演示（展示所有功能）
python -m rich
```

这将在终端中展示 Rich 的全部功能，包括颜色、表格、Markdown、代码高亮等。

### 代码验证

```python
# 新建 test_rich.py
from rich.console import Console

console = Console()
console.print("[bold green]Rich 安装成功！[/bold green] :white_check_mark:")
console.print(f"Rich 版本: [bold cyan]{__import__('rich').__version__}[/bold cyan]")
```

运行：
```bash
python test_rich.py
```

**成功标志**:
- 终端显示绿色加粗的"Rich 安装成功！"
- 显示 Rich 版本号

---

## 四、配置终端环境

### Windows 终端配置

Windows 10 版本 1903+ 的 Windows Terminal 默认支持 ANSI。
旧版 Windows CMD 需要额外配置：

```python
# 在代码中强制启用颜色
from rich.console import Console
console = Console(force_terminal=True)
```

或设置环境变量：
```bash
# PowerShell
$env:FORCE_COLOR = "1"

# CMD
set FORCE_COLOR=1
```

### 检查终端是否支持颜色

```python
from rich.console import Console
console = Console()
print(f"终端支持颜色: {console.is_terminal}")
print(f"颜色深度: {console.color_system}")
# 可能输出: None, "standard", "256", "truecolor"
```

### Jupyter Notebook 支持

```bash
pip install rich[jupyter]
```

```python
# Jupyter 中使用
from rich import print
print("[bold]Hello[/bold] Jupyter!")
```

---

## 五、可选依赖

### Markdown 渲染依赖

```bash
# 安装 Markdown 渲染支持
pip install rich[markdown]
```

### 完整依赖（所有功能）

```bash
pip install "rich[all]"
```

**包含内容**:
- `markdown-it-py`: Markdown 解析
- `pygments`: 语法高亮
- `typing_extensions`: 类型扩展

---

## 六、版本管理

### 查看已安装版本

```bash
pip show rich
```

**输出示例**:
```
Name: rich
Version: 13.9.4
Summary: Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal
Home-page: https://github.com/Textualize/rich
Author: Will McGugan
License: MIT
```

### 升级 Rich

```bash
pip install --upgrade rich
```

### 安装特定版本

```bash
# 安装最新稳定版
pip install rich==13.9.4

# 安装最低版本约束
pip install "rich>=13.0.0,<14.0.0"
```

---

## 七、虚拟环境安装（最佳实践）

**AI 执行说明**: 建议在虚拟环境中安装 Rich

```bash
# 创建虚拟环境
python -m venv venv

# 激活（macOS/Linux）
source venv/bin/activate

# 激活（Windows CMD）
venv\Scripts\activate.bat

# 激活（Windows PowerShell）
venv\Scripts\Activate.ps1

# 安装 Rich
pip install rich

# 验证
python -c "from rich.console import Console; Console().print('[green]OK[/green]')"
```

---

## 完成确认

### 检查清单
- [ ] Python 3.8+ 已安装
- [ ] pip 可用
- [ ] Rich 已成功安装（`pip show rich` 显示版本）
- [ ] `python -m rich` 演示运行成功
- [ ] 终端支持颜色输出

### 下一步
继续阅读 [快速开始](02-quickstart.md) 学习 Rich 的基本用法


path: guides/02-quickstart.md
content: # 快速开始

**适用场景**: 已安装 Rich，开始学习基本用法

---

## 一、最简单的用法

### 使用 Rich 的 print 函数

**AI 执行说明**: AI 可以直接生成并运行以下代码

```python
from rich import print

# 使用标记语法添加样式
print("[bold magenta]Hello[/bold magenta], [green]World[/green]! :sparkles:")

# 渲染 Python 对象
print({"name": "rich", "awesome": True})

# 渲染列表
print([1, 2, 3, "four", "five"])
```

**期望效果**:
- "Hello" 显示为加粗品红色
- "World" 显示为绿色
- 闪光表情 ✨
- Python 对象以彩色语法高亮形式显示

---

## 二、Console 对象

`Console` 是 Rich 的核心对象，提供完整的终端输出控制。

**AI 执行说明**: AI 将使用 Console 对象管理所有输出

```python
from rich.console import Console

# 创建 Console 实例（通常创建一次，全局复用）
console = Console()

# 基本打印
console.print("Hello, World!")

# 带样式打印
console.print("[bold red]错误[/bold red]: 文件未找到")
console.print("[yellow]警告[/yellow]: 内存使用率较高")
console.print("[green]成功[/green]: 任务已完成")

# 打印到 stderr
error_console = Console(stderr=True)
error_console.print("[bold red]严重错误[/bold red]: 数据库连接失败")
```

### Console 常用参数

```python
# 禁用颜色（用于日志文件等纯文本场景）
console = Console(no_color=True)

# 强制设置终端宽度
console = Console(width=120)

# 写入文件
with open("output.txt", "w") as f:
    console = Console(file=f)
    console.print("写入文件的内容")

# 输出 HTML（用于保存截图）
console = Console(record=True)
console.print("[bold]Rich 输出[/bold]")
html = console.export_html()
```

---

## 三、标记语法（Markup）

Rich 使用类似 BBCode 的标记语法来设置样式。

### 基本样式

```python
from rich.console import Console
console = Console()

# 加粗、斜体、下划线
console.print("[bold]加粗文本[/bold]")
console.print("[italic]斜体文本[/italic]")
console.print("[underline]下划线文本[/underline]")
console.print("[strikethrough]删除线文本[/strikethrough]")

# 组合样式
console.print("[bold italic red]加粗红色斜体[/bold italic red]")
```

### 颜色设置

```python
# 使用颜色名称
console.print("[red]红色[/red]")
console.print("[green]绿色[/green]")
console.print("[blue]蓝色[/blue]")
console.print("[yellow]黄色[/yellow]")
console.print("[cyan]青色[/cyan]")
console.print("[magenta]品红[/magenta]")
console.print("[white]白色[/white]")

# 使用十六进制颜色
console.print("[#ff0000]十六进制红色[/#ff0000]")
console.print("[color(9)]ANSI 颜色9[/color(9)]")

# 设置背景色
console.print("[on red]红色背景[/on red]")
console.print("[white on blue]蓝底白字[/white on blue]")
```

### 转义标记

```python
# 如果需要显示方括号，使用转义
console.print("\\[不是标记]")
# 或使用 escape 函数
from rich.markup import escape
console.print(escape("[这是字面量方括号]"))
```

---

## 四、渲染表格

**AI 执行说明**: AI 可以根据数据自动生成表格代码

```python
from rich.console import Console
from rich.table import Table

console = Console()

# 创建表格
table = Table(title="城市人口统计")

# 添加列
table.add_column("城市", style="cyan", no_wrap=True)
table.add_column("省份", style="magenta")
table.add_column("人口（万）", justify="right", style="green")
table.add_column("GDP（亿）", justify="right")

# 添加行
table.add_row("上海", "上海市", "2489", "44652")
table.add_row("北京", "北京市", "2154", "40270")
table.add_row("广州", "广东省", "1882", "28839")
table.add_row("深圳", "广东省", "1756", "32388")

console.print(table)
```

### 表格样式

```python
from rich import box

# 不同边框样式
table = Table(box=box.ROUNDED)      # 圆角边框
table = Table(box=box.SIMPLE)       # 简单样式
table = Table(box=box.MINIMAL)      # 极简样式
table = Table(box=box.MARKDOWN)     # Markdown 表格格式
table = Table(show_header=False)    # 隐藏表头
table = Table(show_lines=True)      # 显示行分隔线
```

---

## 五、Panel 面板

```python
from rich.console import Console
from rich.panel import Panel

console = Console()

# 基本面板
console.print(Panel("Hello, World!"))

# 带标题的面板
console.print(Panel("任务执行完成", title="状态"))

# 带副标题的面板
console.print(Panel(
    "[green]所有测试通过[/green]",
    title="[bold]测试报告[/bold]",
    subtitle="pytest v7.4.0"
))

# 自定义边框样式
from rich import box
console.print(Panel("内容", border_style="blue"))
console.print(Panel("内容", box=box.DOUBLE))
```

---

## 六、进度条

### 使用 track 函数（最简单）

**AI 执行说明**: AI 可以为循环操作自动添加进度条

```python
from rich.progress import track
import time

# 最简单的进度条
for item in track(range(20), description="处理中..."):
    time.sleep(0.1)  # 模拟工作
```

### 使用 Progress 类（更多控制）

```python
from rich.progress import Progress
import time

with Progress() as progress:
    task1 = progress.add_task("[red]下载...", total=100)
    task2 = progress.add_task("[green]处理...", total=100)
    task3 = progress.add_task("[blue]上传...", total=100)

    while not progress.finished:
        progress.update(task1, advance=0.9)
        progress.update(task2, advance=0.6)
        progress.update(task3, advance=0.3)
        time.sleep(0.02)
```

---

## 七、美化打印 Python 对象

**AI 执行说明**: AI 可以安装 Rich 为默认的 pretty printer

```python
# 方式1: 使用 pprint 函数
from rich.pretty import pprint

my_dict = {
    "name": "Rich",
    "version": "13.9.4",
    "features": ["color", "table", "progress", "markdown"],
    "nested": {"key": "value", "number": 42}
}
pprint(my_dict)

# 方式2: 全局安装（替换 Python 内置 pprint）
from rich import pretty
pretty.install()

# 之后所有 Python REPL 输出都会自动美化
[1, 2, 3, "hello", {"key": "value"}]
```

---

## 八、Inspect 对象检查

```python
from rich import inspect

# 检查对象的属性和方法
class MyClass:
    """示例类"""
    def __init__(self, name: str):
        self.name = name

    def greet(self) -> str:
        """返回问候语"""
        return f"Hello, {self.name}!"

obj = MyClass("Rich")
inspect(obj, methods=True)
# 显示对象的所有属性、方法、类型信息和文档字符串
```

---

## 九、Markdown 渲染

```python
from rich.console import Console
from rich.markdown import Markdown

console = Console()

markdown_text = """
# Rich 库介绍

Rich 是一个 **Python 库**，可以在终端中渲染 *富文本*。

## 主要功能

- 颜色和样式
- 表格渲染
- 进度条
- 代码高亮

## 代码示例

```python
from rich import print
print("[bold]Hello[/bold]!")
```

> 更多信息请访问 [Rich 文档](https://rich.readthedocs.io)
"""

md = Markdown(markdown_text)
console.print(md)
```

---

## 十、Rule 分隔线

```python
from rich.console import Console
from rich.rule import Rule

console = Console()

# 基本分隔线
console.print(Rule())

# 带标题的分隔线
console.print(Rule("分隔标题"))

# 自定义样式
console.print(Rule("[bold red]错误报告[/bold red]", style="red"))
console.print(Rule("完成", align="left"))
```

---

## 完成确认

### 检查清单
- [ ] 成功使用 `print` 函数输出彩色文本
- [ ] 创建了 `Console` 对象并使用标记语法
- [ ] 渲染了一个表格
- [ ] 添加了进度条
- [ ] 使用了 Panel 面板

### 下一步
继续阅读 [高级用法](03-advanced-usage.md) 学习语法高亮、日志集成、Live 动态渲染等高级功能


path: guides/03-advanced-usage.md
content: # 高级用法

**适用场景**: 掌握 Rich 基础后，学习语法高亮、日志集成、Live 动态渲染、自定义主题等高级功能

---

## 一、语法高亮（Syntax）

Rich 使用 Pygments 对代码进行语法高亮。

**AI 执行说明**: AI 可以将代码片段以语法高亮形式输出

```python
from rich.console import Console
from rich.syntax import Syntax

console = Console()

# 高亮显示代码字符串
code = '''
def fibonacci(n: int) -> int:
    """计算斐波那契数列第 n 项"""
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))
'''

syntax = Syntax(code, "python", theme="monokai", line_numbers=True)
console.print(syntax)
```

### 从文件读取并高亮

```python
from rich.syntax import Syntax
from rich.console import Console

console = Console()

# 直接读取并高亮文件
syntax = Syntax.from_path(
    "my_script.py",
    theme="dracula",
    line_numbers=True,
    line_range=(1, 50),   # 只显示第 1-50 行
    highlight_lines={10, 20, 30}  # 高亮特定行
)
console.print(syntax)
```

### 常用主题

```python
# 可用主题（Pygments 主题）:
# "monokai"       - 深色，最流行
# "dracula"       - 深色紫色系
# "github-dark"   - GitHub 暗色
# "solarized-dark" - Solarized 暗色
# "friendly"      - 浅色

# 列出所有可用主题
from pygments.styles import get_all_styles
for style in get_all_styles():
    print(style)
```

---

## 二、日志集成（Logging）

将 Rich 集成到 Python 标准 logging 系统中。

**AI 执行说明**: AI 可以将现有日志代码替换为 Rich 日志格式

```python
import logging
from rich.logging import RichHandler

# 配置使用 Rich Handler
logging.basicConfig(
    level=logging.DEBUG,
    format="%(message)s",
    datefmt="[%X]",
    handlers=[RichHandler()]
)

log = logging.getLogger("rich")
log.info("应用启动")
log.warning("磁盘空间不足: %s%%", 85)
log.error("连接数据库失败")

try:
    1 / 0
except ZeroDivisionError:
    log.exception("发生异常")
```

### 高级日志配置

```python
import logging
from rich.logging import RichHandler
from rich.console import Console

# 自定义 Console（写入文件）
file_console = Console(file=open("app.log", "w"))

logging.basicConfig(
    level=logging.INFO,
    format="%(name)s: %(message)s",
    handlers=[
        RichHandler(
            rich_tracebacks=True,       # 美化异常追踪
            tracebacks_show_locals=True, # 显示局部变量
            show_time=True,              # 显示时间
            show_path=True,              # 显示文件路径
            markup=True,                 # 启用标记语法
        ),
        logging.FileHandler("app.log")
    ]
)
```

---

## 三、美化异常追踪（Traceback）

**AI 执行说明**: AI 可以在项目中安装 Rich traceback 替换默认异常输出

```python
from rich.traceback import install

# 全局安装（替换 Python 默认异常输出）
install(
    show_locals=True,   # 显示局部变量值
    width=120,          # 设置输出宽度
    extra_lines=5,      # 显示额外上下文行数
    theme="monokai",    # 代码高亮主题
    word_wrap=True,     # 启用自动换行
)

# 之后所有未捕获的异常都会以 Rich 格式显示
def process_data(data: dict):
    result = data["missing_key"]  # KeyError
    return result

process_data({})
```

### 手动捕获并渲染异常

```python
from rich.console import Console
console = Console()

try:
    x = 1 / 0
except ZeroDivisionError:
    console.print_exception(show_locals=True)
```

---

## 四、Live 动态渲染

`Live` 允许在终端中动态更新内容，适用于实时监控、仪表板等场景。

**AI 执行说明**: AI 可以将静态输出改造为动态实时显示

```python
from rich.console import Console
from rich.live import Live
from rich.table import Table
import time

console = Console()

def generate_table(iteration: int) -> Table:
    """生成动态更新的表格"""
    table = Table(title=f"实时监控 - 迭代 {iteration}")
    table.add_column("服务")
    table.add_column("状态")
    table.add_column("响应时间")

    import random
    services = ["API 服务", "数据库", "缓存", "消息队列"]
    for service in services:
        status = "[green]正常[/green]" if random.random() > 0.2 else "[red]异常[/red]"
        latency = f"{random.randint(10, 200)}ms"
        table.add_row(service, status, latency)

    return table

with Live(generate_table(0), refresh_per_second=2) as live:
    for i in range(10):
        time.sleep(0.5)
        live.update(generate_table(i))
```

### Live 与 Progress 结合

```python
from rich.live import Live
from rich.progress import Progress, SpinnerColumn, TextColumn
from rich.panel import Panel
from rich.layout import Layout
import time

with Progress(
    SpinnerColumn(),
    TextColumn("[progress.description]{task.description}"),
    transient=True,  # 完成后清除进度条
) as progress:
    task = progress.add_task("下载数据...", total=100)
    for i in range(100):
        time.sleep(0.05)
        progress.advance(task)
```

---

## 五、布局（Layout）

`Layout` 用于创建多区域布局，适合构建复杂 TUI 界面。

```python
from rich.layout import Layout
from rich.console import Console
from rich.panel import Panel

console = Console()
layout = Layout()

# 垂直分割（上下）
layout.split_column(
    Layout(name="header", size=3),
    Layout(name="body"),
    Layout(name="footer", size=3),
)

# 水平分割（左右）
layout["body"].split_row(
    Layout(name="sidebar", size=30),
    Layout(name="main"),
)

# 填充内容
layout["header"].update(Panel("[bold]应用标题[/bold]", style="white on blue"))
layout["sidebar"].update(Panel("导航菜单\n- 首页\n- 设置\n- 帮助"))
layout["main"].update(Panel("主内容区域"))
layout["footer"].update(Panel("[dim]状态: 就绪[/dim]"))

console.print(layout)
```

---

## 六、树形结构（Tree）

```python
from rich.console import Console
from rich.tree import Tree
from rich import print

console = Console()

# 创建目录树
tree = Tree("[bold]项目结构[/bold]")

src = tree.add("[bold cyan]src/[/bold cyan]")
src.add("[green]main.py[/green]")
src.add("[green]config.py[/green]")

tests = src.add("[bold cyan]tests/[/bold cyan]")
tests.add("[green]test_main.py[/green]")
tests.add("[green]test_config.py[/green]")

utils = src.add("[bold cyan]utils/[/bold cyan]")
utils.add("[green]helpers.py[/green]")
utils.add("[green]validators.py[/green]")

tree.add("[yellow]README.md[/yellow]")
tree.add("[yellow]pyproject.toml[/yellow]")

console.print(tree)
```

---

## 七、Columns 列布局

```python
from rich.columns import Columns
from rich.console import Console
from rich.panel import Panel

console = Console()

# 多列显示
items = [
    Panel("Python", style="cyan"),
    Panel("JavaScript", style="yellow"),
    Panel("Rust", style="red"),
    Panel("Go", style="blue"),
    Panel("TypeScript", style="blue"),
    Panel("Java", style="magenta"),
]

console.print(Columns(items))

# 列布局文本
languages = ["Python", "JavaScript", "Rust", "Go", "TypeScript", "Java", "C++", "Kotlin"]
console.print(Columns(languages, padding=(0, 2), equal=True))
```

---

## 八、自定义主题（Theme）

**AI 执行说明**: AI 可以为项目创建统一的样式主题

```python
from rich.console import Console
from rich.theme import Theme

# 定义自定义主题
custom_theme = Theme({
    "info": "bold cyan",
    "warning": "bold yellow",
    "error": "bold red",
    "success": "bold green",
    "highlight": "bold white on blue",
    "dim.text": "dim",
    "url": "underline blue",
})

console = Console(theme=custom_theme)

# 使用自定义样式
console.print("[info]信息[/info]: 服务已启动")
console.print("[warning]警告[/warning]: 配置文件未找到，使用默认配置")
console.print("[error]错误[/error]: 无法连接数据库")
console.print("[success]成功[/success]: 数据导出完成")
console.print("[highlight]重要提示[/highlight]")
```

---

## 九、导出 HTML 和 SVG

```python
from rich.console import Console

# 创建记录模式的 Console
console = Console(record=True, width=100)

console.print("[bold red]Rich 输出演示[/bold red]")
console.print("[green]这是一段绿色文本[/green]")

from rich.table import Table
table = Table("列1", "列2", "列3")
table.add_row("A", "B", "C")
table.add_row("D", "E", "F")
console.print(table)

# 导出为 HTML
html = console.export_html(inline_styles=True)
with open("output.html", "w") as f:
    f.write(html)

# 导出为 SVG（更精准的截图）
svg = console.export_svg(title="Rich 演示")
with open("output.svg", "w") as f:
    f.write(svg)

# 导出为纯文本
text = console.export_text()
with open("output.txt", "w") as f:
    f.write(text)
```

---

## 十、自定义进度条

```python
from rich.progress import (
    Progress,
    BarColumn,
    TextColumn,
    TimeRemainingColumn,
    TimeElapsedColumn,
    MofNCompleteColumn,
    SpinnerColumn,
    FileSizeColumn,
    TotalFileSizeColumn,
    TransferSpeedColumn,
    DownloadColumn,
)
import time

# 完整自定义进度条
with Progress(
    SpinnerColumn(),
    TextColumn("[progress.description]{task.description}"),
    BarColumn(),
    MofNCompleteColumn(),
    TimeElapsedColumn(),
    TimeRemainingColumn(),
) as progress:
    task = progress.add_task("[cyan]处理文件...", total=200)
    for _ in range(200):
        time.sleep(0.01)
        progress.advance(task)

# 文件下载进度条
with Progress(
    TextColumn("[bold blue]{task.fields[filename]}"),
    BarColumn(),
    DownloadColumn(),
    TransferSpeedColumn(),
    TimeRemainingColumn(),
) as progress:
    task = progress.add_task(
        "下载中",
        total=1024 * 1024,  # 1MB
        filename="large_file.zip"
    )
    for _ in range(1024):
        time.sleep(0.001)
        progress.advance(task, 1024)
```

---

## 十一、Status 状态指示器

```python
from rich.console import Console
from rich.status import Status
import time

console = Console()

# 显示加载状态
with console.status("[bold green]正在连接数据库...", spinner="dots") as status:
    time.sleep(2)
    status.update("[bold blue]正在加载数据...")
    time.sleep(1)
    status.update("[bold yellow]正在处理...")
    time.sleep(1)

console.print("[bold green]操作完成！[/bold green]")

# 可用的 spinner 名称:
# "dots", "dots2", "dots12", "line", "pipe",
# "star", "star2", "flip", "arrow", "bouncingBar",
# "bouncingBall", "clock", "earth", "moon"
```

---

## 十二、Prompt 交互输入

```python
from rich.prompt import Prompt, Confirm, IntPrompt, FloatPrompt

# 文本输入（带默认值）
name = Prompt.ask("请输入你的姓名", default="匿名用户")

# 带选择限制的输入
color = Prompt.ask(
    "选择颜色",
    choices=["red", "green", "blue"],
    default="blue"
)

# 整数输入
age = IntPrompt.ask("请输入年龄", default=18)

# 浮点数输入
score = FloatPrompt.ask("请输入分数", default=0.0)

# 确认提示
if Confirm.ask("确认执行操作吗？"):
    print("执行操作")
else:
    print("已取消")

# 密码输入
from rich.prompt import Prompt
[REDACTED_SECRET]"请输入密码", password=True)
```

---

## 十三、与 print 和 pprint 集成

**AI 执行说明**: AI 可以在入口文件中一次性替换所有输出函数

```python
# 在项目入口文件顶部添加
from rich import pretty, traceback

# 替换 pprint
pretty.install()

# 替换 traceback
traceback.install(show_locals=True)

# 可选: 替换 print（注意可能影响性能）
# from rich import print  # 不建议全局替换，仅在需要时局部使用
```

---

## 常用参数速查

| 功能 | 类/函数 | 关键参数 |
|------|---------|---------|
| 基本输出 | `Console.print()` | `style`, `justify`, `end`, `highlight` |
| 表格 | `Table` | `title`, `box`, `show_header`, `show_lines` |
| 进度条 | `Progress` | `transient`, `auto_refresh`, `refresh_per_second` |
| 面板 | `Panel` | `title`, `subtitle`, `border_style`, `box` |
| 语法高亮 | `Syntax` | `theme`, `line_numbers`, `line_range` |
| 实时更新 | `Live` | `refresh_per_second`, `transient`, `auto_refresh` |
| 日志 | `RichHandler` | `rich_tracebacks`, `show_time`, `show_path` |
| 主题 | `Theme` | 自定义样式字典 |

---

## 完成确认

### 检查清单
- [ ] 学会使用语法高亮显示代码
- [ ] 将 Rich Handler 集成到 logging
- [ ] 使用 Traceback 替换默认异常输出
- [ ] 使用 Live 创建动态更新界面
- [ ] 创建自定义主题
- [ ] 使用 Prompt 实现交互式输入

### 下一步
如遇到问题，查看 [常见问题](../troubleshooting.md)


path: troubleshooting.md
content: # 常见问题与解决方案

---

## 问题分类说明

**简单问题（1-2步排查）**: 安装问题、基本配置错误  
**中等问题（3-5步排查）**: 样式不生效、终端兼容性问题  
**复杂问题（5-10步排查）**: 性能问题、多线程输出混乱、Jupyter 集成问题

---

## 安装问题

### 1. ModuleNotFoundError: No module named 'rich'【简单问题】

**问题描述**: 代码运行时提示找不到 `rich` 模块

**排查步骤**:
```bash
# 确认 Python 环境
which python
python --version

# 确认 rich 是否安装到当前环境
pip show rich

# 在当前 Python 环境中检查
python -c "import rich; print(rich.__version__)"
```

**常见原因**:
- Rich 安装到了其他 Python 环境（如系统 Python vs 虚拟环境）(50%)
- 使用了多个 Python 版本（python2/python3 混用）(30%)
- IDE 使用的解释器与命令行不同 (20%)

**解决方案**:

**方案A（推荐）**: 激活正确的虚拟环境后安装
```bash
# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装 rich
pip install rich
```

**方案B**: 使用完整路径安装
```bash
# 找到正确的 pip
python -m pip install rich
# 或
python3 -m pip install rich
```

**方案C（IDE 问题）**: 检查 IDE 解释器设置
- VS Code: `Ctrl+Shift+P` -> "Python: Select Interpreter"
- PyCharm: Settings -> Project -> Python Interpreter

---

### 2. Rich 版本过旧，某些功能不可用【简单问题】

**问题描述**: 使用了较新的 API，但提示 `AttributeError` 或 `ImportError`

**排查步骤**:
```bash
# 查看当前版本
python -c "import rich; print(rich.__version__)"

# 查看完整包信息
pip show rich
```

**常见原因**:
- 安装的是旧版本 Rich（如 10.x，而 `Live`、`Layout` 等需要 12+）
- 项目的 `requirements.txt` 锁定了旧版本

**解决方案**:

```bash
# 升级到最新版
pip install --upgrade rich

# 或安装特定版本
pip install "rich>=13.0.0"
```

**版本功能对照**:
- Rich 10.x: Table、Progress、Panel 等基础功能
- Rich 12.x: 新增 Layout、Columns 等
- Rich 13.x: 性能改进，SVG 导出

---

## 颜色和样式问题

### 3. 终端不显示颜色，输出的是原始 ANSI 代码【中等问题】

**问题描述**: 终端输出类似 `\x1b[1m加粗\x1b[0m` 的原始转义序列，或完全不显示颜色

**排查步骤**:
```python
from rich.console import Console
console = Console()

# 检查终端类型
print(f"is_terminal: {console.is_terminal}")
print(f"color_system: {console.color_system}")
print(f"is_dumb_terminal: {console.is_dumb_terminal}")
```

**常见原因**:
- 输出被重定向到文件或管道，Rich 自动检测到非终端禁用颜色 (40%)
- Windows 旧版 CMD 不支持 ANSI (30%)
- 某些 CI 环境（GitHub Actions 等）需要明确启用颜色 (20%)
- 终端设置了 `NO_COLOR` 或 `TERM=dumb` 环境变量 (10%)

**解决方案**:

**方案A（强制颜色）**:
```python
from rich.console import Console
# force_terminal=True 强制启用颜色
console = Console(force_terminal=True)
console.print("[bold red]强制彩色输出[/bold red]")
```

**方案B（CI 环境）**: 设置环境变量
```bash
# 在 CI 配置中添加
export FORCE_COLOR=1
# 或
export TERM=xterm-256color
```

**方案C（检查环境变量）**:
```bash
# 查看是否设置了禁用颜色的变量
echo $NO_COLOR
echo $TERM
echo $FORCE_COLOR

# 临时移除 NO_COLOR
unset NO_COLOR
```

**方案D（Windows CMD）**:
```python
# 对于 Windows 终端
console = Console(force_terminal=True, color_system="windows")
```

---

### 4. 颜色显示不正确，颜色数量受限【简单问题】

**问题描述**: 颜色不准确，或只显示 8 种/16 种颜色

**排查步骤**:
```python
from rich.console import Console
console = Console()
# 查看支持的颜色深度
print(console.color_system)
# None = 不支持颜色
# "standard" = 8色
# "256" = 256色
# "truecolor" = 1600万色（RGB）
```

**解决方案**:

```bash
# 设置终端支持 256 色
export TERM=xterm-256color

# 设置 True Color 支持
export COLORTERM=truecolor
```

```python
# 强制指定颜色系统
from rich.console import Console
console = Console(color_system="256")        # 256色
console = Console(color_system="truecolor")  # True Color
```

---

### 5. 标记语法不生效，显示了原始方括号文本【中等问题】

**问题描述**: 输出的是 `[bold]文本[/bold]` 而不是加粗文本

**排查步骤**:
```python
from rich.console import Console
console = Console()

# 确认是否在用 rich.console.Console 而不是 builtins.print
console.print("[bold]这应该是加粗的[/bold]")

# 检查是否误用了 no_markup 参数
console.print("[bold]正常标记[/bold]")
console.print("[bold]禁用标记[/bold]", markup=False)  # 会显示原始文本
```

**常见原因**:
- 使用了 Python 内置 `print` 而不是 `rich.console.Console.print` (50%)
- 传入了 `markup=False` 参数 (30%)
- 使用了 `console.out()` 而非 `console.print()`（out 不解析标记）(20%)

**解决方案**:

```python
# 方式1: 使用 Console.print
from rich.console import Console
console = Console()
console.print("[bold]加粗文本[/bold]")  # 正确

# 方式2: 替换内置 print
from rich import print
print("[bold]加粗文本[/bold]")  # 正确

# 如果文本中确实有方括号但不是标记，使用转义
from rich.markup import escape
user_input = "[这是用户输入，不是标记]"
console.print(escape(user_input))  # 安全显示用户输入
```

---

### 6. 表情符号不显示或显示为乱码【简单问题】

**问题描述**: `:sparkles:` 等表情符号显示为问号或乱码

**排查步骤**:
```python
from rich.console import Console
console = Console()
# 检查是否支持 Unicode
print(console.encoding)
```

**解决方案**:

```bash
# 设置终端编码为 UTF-8
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Windows PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
```

```python
# 强制使用 UTF-8 输出
import sys
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

# 或在创建 Console 时指定
from rich.console import Console
console = Console(force_jupyter=False)
```

**注意**: Windows 终端字体也需要支持 Emoji（推荐使用 Windows Terminal + 字体 "Cascadia Code" 或 "Nerd Font"）。

---

## 性能问题

### 7. 大量输出时程序速度明显变慢【复杂问题】

**问题描述**: 在循环中频繁调用 `console.print()` 导致性能下降

**排查步骤**:
```python
import time
from rich.console import Console
console = Console()

# 测量单次 print 时间
start = time.perf_counter()
for _ in range(1000):
    console.print("Hello")
elapsed = time.perf_counter() - start
print(f"1000次打印耗时: {elapsed:.2f}s")
```

**常见原因**:
- 每次 `print` 都触发终端刷新（频率过高）
- 在循环内创建大型 `Table` 对象再打印
- 开启了 `record=True` 导致内存中保存所有输出

**解决方案**:

**方案A（使用 Live 批量更新）**:
```python
from rich.live import Live
from rich.table import Table
import time

def build_table(data):
    table = Table()
    table.add_column("序号")
    table.add_column("数据")
    for row in data:
        table.add_row(str(row[0]), str(row[1]))
    return table

data = []
with Live(build_table(data), refresh_per_second=4) as live:
    for i in range(100):
        data.append((i, i * i))
        if i % 10 == 0:
            live.update(build_table(data))  # 只在必要时刷新
        time.sleep(0.05)
```

**方案B（使用 Progress 替代频繁的 print）**:
```python
from rich.progress import track

results = []
for item in track(range(10000), description="处理中..."):
    results.append(item * 2)
# 处理完成后一次性输出结果
console.print(f"处理完成，共 {len(results)} 项")
```

**方案C（批量构建再打印）**:
```python
from rich.console import Console
from rich.text import Text

console = Console()

# 不要在循环中 print，先构建 Text 对象
text = Text()
for i in range(1000):
    text.append(f"行 {i}\n", style="green" if i % 2 == 0 else "blue")

# 一次性打印
console.print(text)
```

---

### 8. 多线程/多进程输出混乱【复杂问题】

**问题描述**: 多线程程序中 Rich 输出交错混乱，内容互相穿插

**排查步骤**:
```python
# 检查是否有多线程输出到同一 Console
import threading
from rich.console import Console

console = Console()

def worker(thread_id):
    for i in range(10):
        console.print(f"线程 {thread_id}: 步骤 {i}")

# 多线程并发
threads = [threading.Thread(target=worker, args=(i,)) for i in range(5)]
[t.start() for t in threads]
[t.join() for t in threads]
# 输出会混乱
```

**解决方案**:

**方案A（使用线程安全的 Progress）**:
```python
from rich.progress import Progress
import threading
import time

def download_file(progress, task_id, filename):
    for _ in range(100):
        time.sleep(0.01)
        progress.advance(task_id)

with Progress() as progress:
    tasks = []
    for i in range(5):
        task_id = progress.add_task(f"[cyan]下载文件{i}...", total=100)
        tasks.append(task_id)

    threads = [
        threading.Thread(target=download_file, args=(progress, tid, f"file{i}"))
        for i, tid in enumerate(tasks)
    ]
    [t.start() for t in threads]
    [t.join() for t in threads]
```

**方案B（使用 Live 统一渲染）**:
```python
from rich.live import Live
from rich.table import Table
import threading
import time

results = {}
lock = threading.Lock()

def worker(thread_id):
    for i in range(5):
        time.sleep(0.2)
        with lock:
            results[thread_id] = i

table = Table("线程", "进度")

with Live(table, refresh_per_second=4) as live:
    threads = [threading.Thread(target=worker, args=(i,)) for i in range(5)]
    [t.start() for t in threads]

    while any(t.is_alive() for t in threads):
        new_table = Table("线程", "进度")
        with lock:
            for tid, progress in results.items():
                new_table.add_row(f"线程 {tid}", f"{progress}/5")
        live.update(new_table)
        time.sleep(0.1)

    [t.join() for t in threads]
```

---

## Jupyter 和特殊环境问题

### 9. Jupyter Notebook 中 Rich 不显示颜色【中等问题】

**问题描述**: 在 Jupyter Notebook 中 Rich 输出纯文本，没有颜色

**排查步骤**:
```python
from rich.console import Console
console = Console()
print(f"is_jupyter: {console.is_jupyter}")
```

**解决方案**:

```bash
# 确保安装了 Jupyter 支持
pip install "rich[jupyter]"
# 或
pip install jupyter rich
```

```python
# 方式1: 强制 Jupyter 模式
from rich.console import Console
console = Console(force_jupyter=True)
console.print("[bold green]Jupyter 彩色输出[/bold green]")

# 方式2: 使用 rich.jupyter 模块
from rich.jupyter import print as jprint
jprint("[bold]Hello Jupyter![/bold]")
```

---

### 10. 输出到文件时包含 ANSI 转义序列【简单问题】

**问题描述**: 将 Rich 输出重定向到文件时，文件中包含 `\x1b[1m` 等乱码

**排查步骤**:
```bash
# 运行并重定向
python script.py > output.txt
cat output.txt  # 查看是否有 ANSI 转义序列
```

**常见原因**:
- Rich 检测到是终端时会加颜色，但强制启用了颜色

**解决方案**:

**方案A（写入文件时使用 Console 的 file 参数）**:
```python
from rich.console import Console

# 写入文件时，Rich 自动禁用颜色
with open("output.txt", "w", encoding="utf-8") as f:
    file_console = Console(file=f)
    file_console.print("[bold]这行在文件中不会有 ANSI 代码[/bold]")
```

**方案B（同时写入终端和文件）**:
```python
from rich.console import Console

# 终端输出（有颜色）
term_console = Console()

# 文件输出（无颜色）
with open("app.log", "a", encoding="utf-8") as f:
    file_console = Console(file=f, no_color=True)
    message = "操作完成"
    term_console.print(f"[green]{message}[/green]")
    file_console.print(message)
```

**方案C（使用 record 模式导出）**:
```python
from rich.console import Console

console = Console(record=True)
console.print("[bold]Hello World[/bold]")

# 导出纯文本
plain_text = console.export_text()
with open("output.txt", "w") as f:
    f.write(plain_text)

# 导出 HTML（保留颜色）
html = console.export_html()
with open("output.html", "w") as f:
    f.write(html)
```

---

## 获取帮助

### 诊断命令汇总

```python
from rich.console import Console
from rich import __version__

console = Console()

# 检查 Rich 版本
print(f"Rich 版本: {__version__}")

# 检查终端能力
print(f"is_terminal: {console.is_terminal}")
print(f"color_system: {console.color_system}")
print(f"is_jupyter: {console.is_jupyter}")
print(f"is_dumb_terminal: {console.is_dumb_terminal}")
print(f"encoding: {console.encoding}")
print(f"width: {console.width}")
print(f"height: {console.height}")
```

```bash
# 运行 Rich 内置诊断
python -m rich.diagnose

# 运行全功能演示
python -m rich
```

### 参考资源

- GitHub: https://github.com/Textualize/rich
- 官方文档: https://rich.readthedocs.io
- 示例代码: https://github.com/Textualize/rich/tree/master/examples
- 颜色参考: https://rich.readthedocs.io/en/latest/appendix/colors.html
- Issues: https://github.com/Textualize/rich/issues
- Discord: https://discord.gg/textualize

---

**提示**: 如遇到本文档未涵盖的问题，请先运行 `python -m rich.diagnose` 收集诊断信息，再到 GitHub Issues 中搜索或提问


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)