> ⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。
> 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。
<!-- professional-disclaimer-injected -->
> 本内容由 AI 生成，仅供学习参考
<!-- ai-generated-notice -->
rich-cli Skill 文档
一、能力边界：一页纸速查卡
1.1 能做什么
| 能力项 | 说明 | 典型场景 |
|---|---|---|
| 富文本渲染 | 在终端中输出带颜色、样式（粗体、斜体、下划线）的文本 | 日志输出、状态提示、欢迎信息 |
| 语法高亮 | 对代码文件或代码片段进行高亮显示 | 查看 Python/JS/Go 等源码文件 |
| Markdown 预览 | 将 Markdown 文件渲染为带格式的终端输出 | 阅读 README、文档、笔记 |
| 表格与面板 | 输出对齐的表格、带边框的面板 | 展示数据对比、配置信息 |
| 文本标记 | 对文本中的关键词进行高亮标记 | 搜索日志中的错误关键字 |
| 自检与版本 | 运行自检确认安装状态，查看版本号 | 环境验证、排障 |
1.2 不能做什么
| 限制项 | 说明 |
|---|---|
| 不支持图形界面 | 仅限终端文本输出，不生成图片或 GUI 窗口 |
| 不支持交互式编辑 | 不提供光标定位、行内编辑等交互能力 |
| 不支持远程渲染 | 仅渲染本地终端输出，不推送至远程会话 |
| 不处理二进制内容 | 对图片、压缩包等二进制文件不适用 |
| 不替代完整 Markdown 解析器 | 仅支持常见 Markdown 语法子集（标题、列表、代码块、引用、表格） |
1.3 适用对象
- 日常使用终端的开发者、运维人员
- 需要美化命令行脚本输出的自动化工程师
- 在终端中阅读文档、查看代码的技术人员
二、触发方式与场景映射
2.1 触发词
- 主触发词：
rich-cli - 同义场景词：
终端富文本、命令行美化、markdown预览、语法高亮、rich渲染
2.2 场景映射表
| 用户说（大白话） | 实际意图 | 对应操作 |
|---|---|---|
| "帮我把这段日志输出成彩色的" | 富文本渲染 | 使用 rich-cli 的文本样式功能 |
| "我想在终端里看这个 README" | Markdown 预览 | 使用 markdown 渲染功能 |
| "这个 Python 文件帮我高亮显示一下" | 语法高亮 | 使用 syntax 高亮功能 |
| "我的脚本输出太乱了，帮我整理下" | 表格/面板输出 | 使用表格或面板功能 |
| "检查一下 rich-cli 装好没有" | 自检 | 运行 --selftest |
三、标准流程
3.1 前置条件
| 条件 | 检查方式 | 通过标准 |
|---|---|---|
| rich-cli 已安装 | 终端执行 rich-cli --version |
返回版本号（如 1.0.0） |
| 终端支持 ANSI 颜色 | 执行 echo -e "\033[31mred\033[0m" |
显示红色 red 字样 |
| 输入文件可读 | 对文件操作时确认路径存在 | ls -l <文件路径> 无报错 |
3.2 执行步骤
步骤 1：收集输入并确认格式
| 输入类型 | 格式要求 | 示例 |
|---|---|---|
| 纯文本 | 直接传入字符串 | rich-cli "Hello World" |
| 文件路径 | 以 -f 或 --file 指定 |
rich-cli -f readme.md |
| 代码文件 | 以 -s 或 --syntax 指定语言 |
rich-cli -s python app.py |
| 标准输入 | 通过管道传入 | cat log.txt \| rich-cli |
步骤 2：按功能逻辑处理输入
| 功能 | 处理逻辑 | 关键参数 |
|---|---|---|
| 富文本 | 解析样式标记（如 [bold red]）并应用 ANSI 转义序列 |
--style、--color |
| 语法高亮 | 调用内置词法分析器识别语言关键字、字符串、注释 | --syntax <lang>、--theme <name> |
| Markdown 预览 | 逐行解析 Markdown 语法，转换为终端渲染格式 | --markdown、--line-numbers |
| 表格输出 | 解析 CSV 或 JSON 数组，对齐列宽并绘制边框 | --table、--columns |
步骤 3：生成结果并校验完整性
- 输出前检查：确认所有输入已被处理，无遗漏内容
- 渲染后检查：确认颜色/样式已生效，无乱码或转义序列泄漏
- 完整性校验：对文件输入，确认输出行数与源文件行数一致（Markdown 渲染除外）
3.3 输出规范
| 输出类型 | 规范要求 |
|---|---|
| 成功输出 | 渲染后的文本直接打印至 stdout，退出码为 0 |
| 错误输出 | 错误信息以 [bold red]Error:[/bold red] 前缀输出至 stderr，退出码非 0 |
| 帮助信息 | 使用 --help 时输出用法说明，退出码为 0 |
四、置信度门控
4.1 信息不足时的处理
当输入信息不足以完成渲染时，使用 [需核实:字段] 占位符，不编造内容：
| 场景 | 占位示例 |
|---|---|
| 未指定语法高亮语言 | [需核实:language] |
| 文件路径不存在 | [需核实:file_path] |
| 样式标记无法识别 | [需核实:style_token] |
| Markdown 语法无法解析 | [需核实:markdown_syntax] |
4.2 禁止行为
- 不猜测用户未提供的参数值
- 不自动选择语言进行高亮（除非文件扩展名明确）
- 不忽略无法解析的输入内容
五、错误码体系
| 错误码 | 含义 | 提示话术 | 修正步骤 |
|---|---|---|---|
E001 |
输入为空 | 错误：未检测到输入内容。请提供文本、文件路径或通过管道传入数据。 |
1. 确认输入方式；2. 重新执行命令 |
E002 |
文件不存在 | 错误：文件 [路径] 不存在。请检查路径是否正确。 |
1. 使用 ls 确认路径；2. 修正路径后重试 |
E003 |
语法高亮语言不支持 | 错误：不支持的语言 [语言名]。支持的语言列表请使用 --help 查看。 |
1. 查看支持列表；2. 更换语言参数 |
E004 |
样式标记格式错误 | 错误：样式标记 [标记] 格式不正确。正确格式为 [bold red] 或 [italic blue]。 |
1. 检查标记语法；2. 修正后重试 |
E005 |
Markdown 解析失败 | 错误：Markdown 解析失败，第 [行号] 行存在无法识别的语法。 |
1. 检查该行内容；2. 修正语法后重试 |
E006 |
输出编码错误 | 错误：输出编码失败，请确认终端支持 UTF-8。 |
1. 检查终端编码设置；2. 切换至 UTF-8 后重试 |
六、FAQ 反模式
6.1 常见坑与反模式对照
| # | 常见坑 | 反模式（错误做法） | 正确做法 |
|---|---|---|---|
| 1 | 颜色不显示 | 忽略终端颜色支持检查 | 先执行 echo -e "\033[31mred\033[0m" 验证终端支持 |
| 2 | 中文乱码 | 直接输出含中文的文本 | 确认终端编码为 UTF-8，必要时设置 LANG=en_US.UTF-8 |
| 3 | 高亮语言选错 | 手动指定错误语言 | 优先依赖文件扩展名自动识别，手动指定时先确认语言名称 |
| 4 | Markdown 表格错位 | 使用复杂嵌套表格 | 保持表格结构简单，避免单元格内换行 |
| 5 | 管道输入丢失 | 忘记处理 stdin 输入 | 确认命令支持管道输入，必要时使用 - 作为文件参数 |
6.2 反模式对照表
| 反模式 | 问题描述 | 替代方案 |
|---|---|---|
| 过度嵌套样式 | [bold red on blue] 多层嵌套导致渲染混乱 |
使用单一样式或减少嵌套层级 |
| 忽略退出码 | 脚本中不检查 rich-cli 的退出码 | 在脚本中检查 $? 或使用 set -e |
| 硬编码颜色 | 在脚本中硬编码 ANSI 码而非使用 rich-cli | 统一通过 rich-cli 管理样式 |
| 大文件直接渲染 | 对超大文件（>10MB）直接渲染导致卡顿 | 先截取部分内容或分段处理 |
七、渐进式披露
7.1 速查卡（30 秒上手）
# 基本用法
rich-cli "Hello World"
rich-cli -f readme.md --markdown
rich-cli -s python app.py
# 常用参数
--style bold red # 设置样式
--theme monokai # 设置高亮主题
--line-numbers # 显示行号
--help # 查看帮助
7.2 新手路径（5 分钟入门）
- 运行
rich-cli --selftest确认安装正常 - 尝试
rich-cli "Hello [bold red]World[/bold red]"体验富文本 - 使用
rich-cli -f README.md --markdown预览 Markdown 文件 - 使用
rich-cli -s python script.py查看高亮代码
7.3 进阶路径（深入使用）
- 学习样式标记语法：
[bold]、[italic]、[underline]、[red]、[blue]等 - 掌握主题切换：
--theme参数支持monokai、github、solarized等 - 组合使用：将 rich-cli 嵌入 shell 脚本，实现日志着色、状态面板输出
- 管道集成：
cat log.txt | rich-cli --style bold实现流式渲染
八、参数速查表
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
--style |
字符串 | 无 | 设置文本样式，如 bold red |
--color |
字符串 | 终端默认 | 设置文本颜色 |
--syntax |
字符串 | 自动识别 | 指定高亮语言 |
--theme |
字符串 | default |
高亮主题名称 |
--markdown |
布尔 | false |
启用 Markdown 渲染 |
--line-numbers |
布尔 | false |
显示行号 |
--table |
布尔 | false |
启用表格模式 |
--columns |
字符串 | 无 | 表格列定义（逗号分隔） |
--file / -f |
路径 | 无 | 输入文件路径 |
--selftest |
布尔 | false |
运行自检 |
--version |
布尔 | false |
显示版本号 |
--help |
布尔 | false |
显示帮助信息 |
九、用户协议
<!-- user-agreement-injected -->
使用 rich-cli Skill 即表示您同意以下条款：
- 责任承担：使用者自行承担使用本 Skill 的全部责任。因使用本 Skill 导致的任何直接或间接损失，Skill 作者及贡献者不承担任何责任。
- 禁止反向工程：不得对本 Skill 文档及其引用的代码进行反向工程、反编译、破解或试图提取底层算法。
- 合规使用：使用者应确保使用场景符合当地法律法规及所在组织的安全规范。
- 无担保声明：本 Skill 按"现状"提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权性。
十、许可证（License）
<!-- professional-license-embedded -->
MIT License
MIT License
Copyright (c) 2024 TerminalCraft Studio
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
本 Skill 由 AI 辅助生成，仅供参考。使用前请阅读相关文档。
