Python 写个终端备忘录，告别重复 Google 命令
1. 你也有这个习惯吗
下午 2:17，你正在终端里用 llama.cpp 启动本地 LLM 服务。你知道 GPU 卸载的 flag 是 --ngl 或者可能是 -ngl……但后面是加空格还是等号？默认是多少层？
你 alt-tab 切到浏览器，输入”llama.cpp gpu layers flag”。翻过三个 Stack Overflow 帖子、一个 2023 年的 Reddit 讨论、官方文档（说实话，官方文档本身就是一个搜索挑战）——几分钟后回到终端，打上命令。
如果你是个开发者，或者写代码时间久到脑子里存了一个装满”半记得命令”的仓库，你一定懂这个场景。
我们不是因为老了记性不好。我们是因为用的工具太庞大、太专业、使用频率刚好够让人沮丧，但不够形成肌肉记忆。
我们已经接受了这就是”常态”。但如果不必这样呢？
2. 终端是我们住的地方——帮助为什么不能也在那里
回想你作为一个开发者，大部分生产力时间花在哪里。对很多人来说，不是花哨的 IDE 或云仪表板——是终端。那个等宽字体里闪烁的光标，是你管理文件、运行脚本、部署应用、调试问题的地方。
但需要帮助时，你离开终端。跳转到浏览器，搜索，复制粘贴，回来。一个小小的上下文切换，每天乘以几十次——累积成认知疲劳。
这就是 Fabio Matricardi 构建 TerminalHelper 的出发点：一个轻量级、基于 Python 的 CLI 应用，把你的终端变成一个自包含、可搜索的文档中心。不离开终端。 就是你的速查表，一个命令就能找到。
3. 核心技术：三个关键函数
整个应用围绕三个简单的函数构建，没有复杂框架。
找到正确的目录
def get_base_path() -> Path:
"""返回脚本或可执行文件所在目录"""
if getattr(sys, "frozen", False):
return Path(sys.executable).parent
return Path(__file__).parent
这个函数解决了一个意料之外的问题：当你运行 python wiki-help.py 时，__file__ 指向脚本位置。但当 PyInstaller 打包成单个 .exe 后，脚本的行为变了。秘诀是 sys.executable 始终指向实际运行的程序——无论是 python.exe 还是 WikiHelp.exe。
使用 .parent 就能得到可执行文件所在的文件夹。从那里，只需一个相对路径就能找到 documentation/ 目录。
这个设计的妙处：更新文档不需要重新构建应用。
扫描加载文档
def load_documents(doc_dir: Path) -> list:
if not doc_dir.exists():
print("📄 No documents found")
return []
return sorted(doc_dir.glob("*.md"), doc_dir.glob("*.txt"))
这个函数体现了关键原则：乐于助人，不乱报错。真实世界的工具会遇到混乱的环境，代码应该预期这一点。
交互循环
核心交互流程：
- 获取文档文件夹路径，加载可用文件
- 如果找不到文件，优雅退出并显示清晰消息
- 菜单循环：列出文档 → 输入关键词搜索 → Rich 高亮匹配结果 → 按回车返回列表
- 新增一个 Markdown 文件到文件夹，下次启动自动出现——零配置
def main() -> None:
doc_dir = get_base_path() / "documentation"
docs = load_documents(doc_dir)
if not docs:
console.print("\n[bold red]📄 No documents found.[/bold red]")
return
# 交互循环...
4. 打包与使用
安装依赖和运行：
# 创建虚拟环境
python -m venv venv
source venv/bin/activate
# 安装依赖
pip install rich pyinstaller
# 运行
python wiki-help.py
# 打包可执行文件
pyinstaller --onefile --name terminal-helper wiki-help.py
⚠️ 关键：用虚拟环境打包。 如果在全局安装中构建，会包含所有已安装的 Python 包，生成的文件体积会大很多。
打包后，把 .md 文档放到可执行文件旁边的 documentation/ 目录。运行程序，输入关键词搜索——就这么简单。
5. 作者的哲学
在职业生涯的这个阶段，我们已经看过太多框架来了又走。学到的一件事是：简单不是妥协，简单是功能。
TerminalHelper 拥抱这种理念：
- 没有隐藏的魔法：每个函数都做一件事
- 没有复杂依赖：Python + Rich 就够了
- 没有昂贵的云端服务：离线可用，数据完全由自己控制
- 没有学习曲线：放个
.md文件进去就能用
“先解决面前的问题，用最简单的工具，为别人留下学习空间。”
项目代码在 GitHub 上：github.com/fabiomatricardi/terminalhelper
6. 使用场景
- 当你只想记住那个 flag 的时候
- 当你教初级开发者时想快速展示正确的命令
- 当深夜调试时不想再打开浏览器分散注意力
- 当你在没有网络的离线环境中工作
它不是 AI 助手。不索引代码库。不预测你的下一个命令。它就在那里，你需要时出现，不需要时隐退。
对于我们这些经验丰富的电脑用户来说：最好的工具不是最复杂的，而是那些融入工作流、让你专注做事的工具。
相关链接：
- GitHub 仓库：github.com/fabiomatricardi/terminalhelper
- Rich 库：github.com/Textualize/rich
- PyInstaller：pyinstaller.org