kh —— 终端命令行速查表

敲 kh git / kh docker / kh tar 查看常用命令的速查页；支持全文搜索、一键复制、 shell 动态补全与中英双语界面。工具面向纯终端场景：无 GUI、无 Web、无服务端依赖； 在管道、脚本或 SSH 等非 TTY 环境下自动降级为纯文本输出，不弹交互、不阻塞等待。

所有速查页均为内置页，编译进二进制，安装即可用，运行时不需要任何数据文件。

特性

• 内置页编译进二进制，安装即用（sheets/ 目录即内置页清单：docker、git、tar、zip）
• 全文搜索，主题名记不全时自动给出排序建议
• 一键复制命令到剪贴板；示例行（$ 开头）展示时前缀置灰、复制时自动去掉前缀
• 命令行轻量语法高亮：命令词加粗、选项青色、字符串黄色、变量品红、注释置灰；页面描述行（源码 # 开头）同样以灰色显示
• 界面提示中英双语，可用 kh lang 切换
• 支持 bash / zsh / fish 动态补全

安装

环境要求

• Rust 工具链（rustc / cargo ≥ 1.85，推荐最新稳定版）
• 安装过程中需要联网下载依赖

方式一：cargo install（推荐）

适用于已 clone 到本地的仓库目录：

git clone <你的仓库地址>
cd <仓库目录>

cargo install --path .

安装完成后可执行文件位于 ~/.cargo/bin/kh。只要该目录在 PATH 中即可直接使用 （使用 cargo 安装的 Rust 工具一般已自动包含此目录）。

方式二：手动编译

不使用 cargo install、或想自己控制二进制位置时：

cd <仓库目录>
cargo build --release

编译产物为 target/release/kh（单文件，内置页已嵌入其中），将其复制到 PATH 中的任意目录即可，例如：

cp target/release/kh ~/.local/bin/

检查 ~/.local/bin 是否在 PATH 中：

echo $PATH | tr ':' '\n' | grep "$HOME/.local/bin" || echo "未包含，请加入 PATH"

方式三：拷贝二进制到其他机器（免安装）

编译产物是自包含单文件（内置页已嵌入其中），可复制到本机其他目录或其他机器 直接使用，目标环境无需 Rust、无需源码、无需任何配置文件。

复制到本机其他目录（Linux / macOS 需加执行权限）：

cp target/release/kh ~/tools/kh
chmod +x ~/tools/kh          # 加上执行权限，否则会报 Permission denied
~/tools/kh --version

复制到其他机器（示例：Linux 服务器）：

scp target/release/kh user@host:~/.local/bin/
ssh user@host 'chmod +x ~/.local/bin/kh'   # 目标机器同样需要执行权限
ssh user@host 'kh git'                     # 验证可用

注意事项：

• 二进制不能跨操作系统或 CPU 架构使用：Linux x86_64 上编译的产物不能直接用于 macOS、Windows 或 ARM 机器，需在对应平台各自编译（或交叉编译）
• Linux / macOS 需要 chmod +x；Windows 复制 .exe 即可，无需加权限
• 目标机器若为较老的 Linux 发行版，可能出现 glibc 版本过旧无法运行的情况， 可用 cargo build --release --target x86_64-unknown-linux-musl 编译静态版分发

验证安装

kh --version     # 输出版本号
kh git           # 显示 git 速查页
kh --help        # 帮助（中英双语）

升级与覆盖旧版本

重新编译安装即可覆盖，升级时需加 --force：

cargo install --path . --force

内置页随二进制编译固定：修改源码 sheets/ 目录下的页面文本后，需要重新编译 安装才会生效。

快速上手

kh git                      # 查看 git 速查页
kh search 提交               # 全文搜索（多关键词需同时命中）
kh git -n 2                 # 只看第 2 条记录
kh git -c                   # 复制第 1 条命令到剪贴板
kh git -n 2 -c              # 复制第 2 条命令
kh ls                       # 列出全部主题
kh lang en                  # 切换为英文界面
kh completions bash >> ~/.bashrc   # 开启 bash 动态补全

页面输出示例：

$ kh docker
docker 6 条

查看本地镜像
docker images

查看运行中的容器
docker ps

语言

界面提示、帮助、报错默认均为中文，可切换为英文（持久化，下次启动仍生效）：

kh lang          # 查看当前语言
kh lang en       # 切换为英文
kh lang zh       # 切换为中文

语言优先级：配置文件（kh lang 写入）> 环境变量 KH_LANG（zh/en）> 默认中文。 配置文件位于数据目录下（Linux 为 ~/.local/share/kh/config）。

命令参考

命令	作用
kh <主题>	查看主题页（等价 kh show <主题>）
kh show <主题>	显式查看，可访问与动作同名的保留字主题（如 kh show search）
kh ls	列出全部主题
kh search <关键词…>	全文搜索；多个关键词需同时命中
kh topics	仅打印主题名列表（供补全脚本回调）
kh lang [zh|en]	查看 / 切换界面语言（缺省中文）
kh completions bash|zsh|fish	输出对应 shell 的补全脚本
kh uninstall [-y]	卸载（删除语言配置数据目录并给出清理指引）
kh -h / kh -v, -V	帮助 / 版本（-v 与 -V 均可）

查看选项（kh <主题> 与 kh show 通用，位置任意）：

选项	作用
-c, --copy	复制所选记录的命令到剪贴板（默认第 1 条）
-n N, --number N	只展示 / 复制第 N 条记录
-i, --interactive	编号菜单交互选择一条记录（非 TTY 时退化为整页展示）

kh 无参数时打印帮助。主题名输入不精确时自动给建议：按前缀、包含、编辑距离 排序；终端下弹出编号菜单可直接选择，非终端则将建议打印到 stderr 并以非零码退出。

页面格式

每个主题页是一个无扩展名的纯文本文件（源码位于 sheets/），文件名即主题名。 格式规则只有两条：以 # 开头的行是描述行（连续多行并入同一条描述），其余行为命令。

# 创建 gzip 压缩包
# 适合分发
tar -czvf archive.tar.gz mydir/

# 解压到指定目录
tar -xvf archive.tar.gz -C /target
$ tar -tvf archive.tar.gz   # 以 $ 开头的行是示例行：展示时 $ 前缀置灰，复制时自动去掉

补充规则：

• 一条记录由描述行与其后的命令块组成；命令块可跨多行（如 heredoc），块内空行保留， 记录之间与块首、块尾的空行仅作排版被忽略
• 只有行首的 # 才是描述行；命令行内的 # 注释属于命令内容（展示/搜索/复制都会带上）， 想加说明请另起一行写 # 描述
• 一条描述后若跟多行命令，仍是同一条记录；-n N / 编号菜单按记录计数
• 主题名以字母或数字开头，可包含 .、_、-；文件需为 UTF-8，兼容 CRLF 行尾
• 渲染时标题行（主题名 + 条数）由程序自绘，不会回写文件

新增或修改内置页：编辑 sheets/ 下的文件后重新编译安装（见「升级与覆盖旧版本」）。

shell 补全

补全脚本由程序自身生成（kh completions <shell>），主题列表动态读取自 kh topics，变更内置页后即时生效。

# bash：将输出追加到 ~/.bashrc
kh completions bash >> ~/.bashrc

# zsh：写入 fpath 目录后重新执行 compinit
kh completions zsh > ~/.zfunc/_kh

# fish：写入标准补全目录
kh completions fish > ~/.config/fish/completions/kh.fish

补全范围：第一位置补动作词与全部主题；kh show 之后补主题。

卸载

kh uninstall          # 交互确认（输入 y 执行，其他键取消）
kh uninstall -y       # 跳过确认（非 TTY / 脚本环境必须加 -y）

卸载命令会删除数据目录（语言配置），并打印剩余的手动清理命令：删除二进制与 shell 配置文件中的补全行（kh uninstall 会直接给出可复制执行的命令）。

若想保留语言设置，卸载前无需额外操作；重新安装后再 kh lang 设置一次即可 （也可以先备份 ~/.local/share/kh/config）。

环境与行为

项目	说明
KH_LANG	界面语言（zh / en），优先级低于 kh lang 写入的配置
NO_COLOR	置位后输出自动去色
XDG_DATA_HOME	Linux 下重定向数据目录（仅存放语言配置）
颜色输出	管道、重定向与非 TTY 场景自动去除 ANSI 转义
剪贴板	依赖图形会话（X11 / Wayland）；无会话时输出提示并以非零码退出，页面正常展示
非 TTY	不弹出任何菜单，不等待输入

开发与测试

cargo test                  # 单元与集成测试
cargo clippy --all-targets  # 保持 0 警告
cargo build --release

源码结构：

src/lib.rs           入口与命令分发
src/main.rs          薄二进制入口
src/cli.rs           命令定义（clap 子命令 + 外部主题兜底）
src/sheet.rs         页面模型、解析与渲染（含语法高亮）
src/store.rs         内置页嵌入、主题列表与语言配置
src/find.rs          建议排序与全文搜索
src/action.rs        各动作实现（查看 / 搜索 / 语言 / 卸载 / 剪贴板）
src/completions.rs   bash / zsh / fish 补全脚本
src/i18n.rs          界面语言（zh / en）与双语模板
sheets/              内置页（docker、git、tar、zip）
tests/parse.rs       集成测试