CmdHint

Mac/Linux 命令动态提示工具，集命令补全、用法查询、命令执行于一体。在终端中输入命令时即可获得智能提示，按 Tab 触发补全菜单，直接回车执行命令，加 ? 前缀查看命令详细说明。

内置 199 条常用命令，覆盖文件操作、搜索、文本处理、权限管理、进程管理、系统信息、磁盘存储、压缩归档、网络、包管理、版本控制、容器、系统服务、用户管理、安全、实用工具等 17 个分类。

---

功能特性

智能补全：输入命令前缀按 Tab 弹出候选菜单，显示命令名称、所属分类和中文描述。支持三种匹配策略——前缀匹配（输入 ls 匹配 ls、lsof、lsblk）、子序列匹配（输入 dc 匹配 docker、docker-compose）、模糊匹配（输入 grpe 也能找到 grep）。

参数补全：输入命令名加空格后按 Tab，显示该命令的常用参数及说明。例如输入 grep 按 Tab 会列出 -r（递归搜索目录）、-i（不区分大小写）、-n（显示行号）等参数。

命令执行：直接输入命令回车即可执行，完整继承终端 TTY，ls 等命令的文件/目录颜色正常显示，支持管道、重定向等 shell 特性。cd 命令也能正常切换目录。

命令查询：输入 ? 加命令名查看详细说明，包括用法语法、所属分类、使用示例和常用参数列表。输入 ?grep -r 可以单独查看某个参数的作用。模糊查询同样有效，输入 ?grpe 也能匹配到 grep。

历史记录：命令历史自动持久化到 ~/.cmdhint_history，支持上下方向键翻阅历史，灰色文字自动建议历史命令。

---

环境要求

• Python 3.8 或更高版本
• prompt_toolkit 3.0 或更高版本

---

安装

[https://github.com/JunJianSyu/cmdhint](https://github.com/JunJianSyu/cmdhint.git)

方式一：一键安装

cd cmdhint
bash install.sh

安装完成后，在任意目录输入 cmdhint 即可启动。如果提示命令未找到，需要将 ~/.local/bin 加入 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Bash 用户将 ~/.zshrc 替换为 ~/.bashrc。

方式二：直接运行

pip install prompt_toolkit
python3 cmdhint/cmdhint.py

无需安装，只要 prompt_toolkit 依赖满足即可直接运行。

方式三：pip 安装

cd cmdhint
pip install -e .
cmdhint

以开发模式安装，修改代码后无需重新安装。

---

使用方法

执行命令

直接输入命令回车执行，和普通终端用法一致：

cmdhint ~ ❯ ls -la
cmdhint ~ ❯ grep -rn 'TODO' src/
cmdhint ~ ❯ echo hello | wc -w
cmdhint ~ ❯ cd /tmp

智能补全

输入命令前缀后按 Tab 键触发补全菜单：

cmdhint ~ ❯ gr<Tab>
  grep    [搜索]   在文件中搜索匹配文本的行
  groups  [用户管理] 显示用户所属的组
  groupadd [用户管理] 创建新用户组

输入命令名加空格后按 Tab 补全参数：

cmdhint ~ ❯ grep <Tab>
  -r    递归搜索目录
  -i    不区分大小写
  -n    显示行号
  -l    只显示文件名
  ...

查看命令说明

用 ? 前缀查询命令的完整说明：

cmdhint ~ ❯ ?tar
  tar - 归档和压缩文件（打包/解包）
    用法: tar [options] [archive] [files]
    分类: 压缩归档
    示例:
      $ tar -czf archive.tar.gz dir/
      $ tar -xzf archive.tar.gz
      $ tar -tf archive.tar.gz
    常用参数:
      -c          创建归档
      -x          解压归档
      -z          使用gzip压缩
      -f          指定归档文件名
      -v          显示详细过程

查看特定参数的说明：

cmdhint ~ ❯ ?tar -z
  -z → 使用gzip压缩

内建命令

命令	说明
:list	按分类列出全部 199 条命令
:search <关键词>	按关键词搜索命令，支持搜索命令名、描述和分类
:stats	显示命令数量统计和分类分布
:help	显示帮助信息
:quit 或 :q	退出 CmdHint

Ctrl+C 不会退出程序，只会取消当前输入。Ctrl+D 退出。

---

命令覆盖范围

分类	命令数	代表命令
文件操作	15	ls, cd, cp, mv, rm, mkdir, touch, ln, tree
文件查看	20	cat, less, head, tail, wc, diff, sort, uniq, cut, vim
搜索	10	find, grep, rg, ag, locate, which, whereis
文本处理	6	sed, awk, xargs, jq, bc
权限管理	6	chmod, chown, sudo, su
进程管理	18	ps, top, htop, kill, lsof, tmux, screen, watch
系统信息	18	uname, whoami, date, env, echo, man, history, alias
磁盘存储	9	df, du, mount, free, lsblk
压缩归档	9	tar, gzip, zip, unzip, bzip2, xz
网络	20	ping, curl, wget, ssh, scp, rsync, netstat, dig, nmap
包管理	15	apt, brew, pip, npm, yarn, cargo, docker
版本控制	1	git
容器	3	docker, docker-compose, kubectl
系统服务	6	systemctl, journalctl, crontab, shutdown
用户管理	6	useradd, userdel, usermod, passwd, groups
安全	7	ssh-keygen, gpg, openssl, md5sum, sha256sum
实用工具	14	clear, sleep, open, pbcopy, xdg-open, source

每条命令均包含中文描述、用法语法、使用示例和常用参数说明。

---

项目结构

cmdhint/
├── cmdhint.py       # 主程序入口，交互式终端界面
├── commands.py      # 命令数据库（199 条命令）
├── matcher.py       # 模糊匹配和补全核心逻辑
├── install.sh       # 一键安装脚本
├── pyproject.toml   # Python 包配置
├── __init__.py      # 包初始化文件
└── README.md        # 本文档