kh —— 终端命令行速查表

敲 kh git / kh docker / kh tar / kh * 查看常用命令的速查页；也可以自建、搜索、 复制、补全自己的命令页。工具面向纯终端场景：无 GUI、无 Web、无服务端依赖；

特性

• 内置 git、tar、docker 等命令页（sheets/ 目录即内置页清单），编译进二进制，安装即可用
• 支持自建页：编辑器模板或多行记录，页面即纯文本文件，方便备份与版本管理
• 全文搜索（内置页与用户页），主题名记不全时自动给出排序建议
• 一键复制命令到剪贴板；示例行自动去掉 $ 前缀
• 语法高亮：描述行与 # 注释置灰，命令词加粗、选项青色、字符串黄色、变量品红
• 界面提示中英双语，可用 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"

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

编译产物 target/release/kh 是自包含单文件（内置页已嵌入其中）， 可复制到本机其他目录或其他机器直接使用，目标环境无需 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/ 目录下的页面文本后，需要重新编译 安装才会生效。

数据目录

用户自建页存放在各平台的标准数据目录，无需手工创建，首次使用时自动生成：

平台	用户页目录
Linux	~/.local/share/kh/sheets/
macOS	~/Library/Application Support/kh/sheets/
Windows	%APPDATA%\kh\sheets\

快速上手

kh git                                            # 查看 git 速查页
kh search 压缩                                    # 全文搜索（内置页 + 用户页）
kh git -n 2                                       # 只看第 2 条记录
kh git -c                                         # 复制第 1 条命令到剪贴板
kh git -n 2 -c                                    # 复制第 2 条命令
kh add vimdiff '比较两文件' 'vim -d f1 f2'        # 内联自建一条记录
kh edit tar                                       # 自定义内置页（先复制为用户页再编辑）
kh completions bash >> ~/.bashrc                  # 开启 bash 动态补全

页面输出示例：

$ kh docker
docker 内置页 · 9 条

查看本地镜像
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 add <主题>	用编辑器模板新建页（默认编辑器为 vi，可用 $EDITOR 指定）
kh add <主题> "<描述>" "<命令>"	内联新建一条记录
kh edit <主题>	编辑页；内置页先复制为用户页
kh rm <主题>	删除用户页（内置页不可删除）
kh ls	列出全部主题（用户 / 内置分组）
kh search <关键词…>	全文搜索；多个关键词需同时命中
kh topics	仅打印主题名列表（供补全脚本回调）
kh completions bash|zsh|fish	输出对应 shell 的补全脚本
kh lang [zh|en]	查看 / 切换界面语言（缺省中文）
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 并以非零码退出。

页面格式

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

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

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

补充规则：

• 一条记录由描述行与其后的命令块组成；命令块可跨多行（如 heredoc），块内空行保留， 记录之间与块首、块尾的空行仅作排版被忽略
• 主题名以字母或数字开头，可包含 .、_、-；文件需为 UTF-8，兼容 CRLF 行尾
• 渲染时标题行（主题名 + 来源/条数）由程序自绘，不会回写文件
• 以 . 开头的文件（如编辑器交换文件）会被忽略，不出现在主题列表中

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 add/edit/rm/show 之后补主题。

数据与备份

用户页即普通文本文件，可直接复制、归档或纳入 git 管理：

ls ~/.local/share/kh/sheets/                                      # 查看全部用户页
cp -r ~/.local/share/kh ~/kh-backup                               # 整目录备份
scp -r ~/.local/share/kh/sheets user@host:~/.local/share/kh/      # 迁移到其他机器

用户数据仅存放在上述目录，删除它即清除全部自建内容（不影响二进制本身）。

卸载

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

卸载命令会删除用户数据目录并打印剩余清理指引。二进制与 shell 配置文件中的补全行 需手动清理：

cargo uninstall kh        # 或直接删除拷贝的 kh 可执行文件
# 从 ~/.bashrc 删除包含 _kh_complete 的行
# rm ~/.zfunc/_kh
# rm ~/.config/fish/completions/kh.fish

若只是重装或更换机器而想保留自建页，仅删除二进制即可，数据目录可保留。

环境与行为

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

开发与测试

cargo test                      # 26 项单元与集成测试
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/              内置页目录（git、tar、docker 等）
tests/parse.rs       集成测试