ThorOdinson246/whatisit-nl2sh

Local natural-language-to-shell command generator. A 941 MB fine-tuned Qwen2.5-Coder-1.5B running on CPU in ~1s.

whatisit‑nl2sh – 将纯英文转换为 shell 命令（离线）

功能说明 – whatisit 是一个小型命令行工具，接受任务的自然语言描述，并返回对应的 Unix shell 命令。它通过 llama.cpp 在本地运行一个 1.5 B 参数的 LLM，因此除非你明确指定远程 OpenAI 兼容端点，否则数据不会离开你的机器。

重要性 – 它能让你快速获取看似正确的命令，无需搜索网络或记住确切语法，同时保护隐私并避免云 API 的延迟。模型很小（约 941 MiB），可在仅 CPU 的笔记本电脑上运行。

快速开始

# 安装 CLI（建议使用 pipx，但普通 pip 也可以）
pipx install whatisit          # 或：pip install whatisit
whatisit setup                 # 下载模型并检查你的 llama.cpp 二进制文件

如果你已有 llama.cpp 构建，可用 --bin-dir 指定给 whatisit。

典型用法

# 简单查询 – 打印命令
whatisit find files bigger than 100MB in this folder
# → find . -size +100M -exec ls -lh {} \;

# 确认后执行命令
whatisit -e compress the logs directory into a tarball

# 获取多个替代方案
whatisit -n 3 list python files modified today

# 在脚本中使用输出
cd "$(whatisit -q the directory holding the largest log file)"

标志：

-e/--execute – 要求确认后执行命令。
-n N – 返回 N 个候选命令。
-q/--quiet – 只输出原始命令（适用于命令替换）。
-t/--timing – 显示生成所花时间。
-p/--prefill-command – 执行前在可编辑提示中打开生成的命令。

你也可以将其集成到 shell 提示符中：

# 添加到 ~/.bashrc 或 ~/.zshrc
eval "$(whatisit shell-init)"

现在 whatisit <request> 会将生成的命令放在下一行提示符，方便编辑。

底层工作原理

模型 – 基于 Qwen2.5‑Coder‑1.5B‑Instruct（或可选的 3 B 变体）的 LoRA 微调版本，量化为 GGUF Q4_K_M（约 941 MiB）。训练使用了 125 k 个 NL‑to‑command 配对。
运行环境 – 模型由 llama.cpp 的 llama-server 提供服务。第一次调用会启动常驻服务器；后续调用很快，因为模型会保持在 RAM 中（1.5 B 模型约 1.6 GiB）。
生成 – 温度 0 的贪婪解码，因此相同查询总是生成相同命令。在 Intel i5‑11320H 上的典型吞吐量：约 39 tokens/s，暖机后延迟约 0.6 秒。
安全层 – 打印前，规则式检查器会扫描命令中的危险模式（递归删除 /、写入块设备、权限提升技巧、反向 shell 等）。被标记的命令会标为 DANGER（绝不自动执行）或 CAUTION（警告但仍可选）。

离线 vs. 远程模式

默认 – 完全离线；请求不会离开主机。
远程 – 在配置中设置 openai_base_url 和 openai_model（或 Ollama 端点），将查询路由到托管 API。工具会在每次远程调用时打印警告。

安装细节

步骤	你需要什么
CLI	`pipx install whatisit`（或在 venv 中 `pip install whatisit`）
模型文件	从 Hugging Face 通过 `huggingface_hub` 下载 `nl2sh-1.5b-Q4_K_M.gguf`（约 941 MiB）
`llama.cpp` 二进制文件	获取预构建版本（`llama-server`、`llama-cli`）或自行构建；Linux 上需要 glibc ≥ 2.34
配置	`whatisit setup --model <path> --bin-dir <path/to/llama.cpp/bin>`

也提供 Nix flake 给 Nix/NixOS 用户，会自动集成 llama.cpp 包。

性能与基准

InterCode‑ALFA 基准（300 个 NL‑to‑shell 任务）
- whatisit（1.5 B）– 62 % 通过率，暖机后中位数延迟 0.59 秒，冷启动 2 秒。
- 可选的 3 B 模型 – 65.7 % 通过率，生成较慢（约 17 tok/s）且 RAM 较高（约 3.4 GiB）。
- 与未调校的 Qwen2.5‑Coder‑7B（61.3 %）和 GPT‑4o（73 %）比较。
相较于未调校的基础模型（54 %）的改进在统计上显著（p ≈ 0.004）。

安全性与限制

安全性 – 规则式黑名单涵盖递归删除、块设备写入、权限变更、网络拉取命令等。它不是沙箱；你仍必须审查输出。
限制 – 仅单轮（无 shell 状态），最大 64‑token 输出（因此不适合多行脚本），仅英文，基准特定性能。

许可证与归属

代码：Apache‑2.0
模型：衍生自 Qwen2.5‑Coder‑1.5B‑Instruct（Apache‑2.0），训练数据来自各种宽松许可来源（MIT、CC‑BY‑4.0、CC0、Apache‑2.0）。完整数据集稍后发布。

下一步

尝试 3 B 模型以获得更高准确度（whatisit setup --size 3b）。
贡献改进安全检查器或增加多轮交互支持。
关注仓库以获取每日更新检查（可通过配置禁用）。

总结 – whatisit 提供一种保护隐私、低资源消耗的方式，将日常英文指令转换为 shell 命令，内置安全过滤器，并可选用远程 API 备用。