CLI Command Explainer

cmd-explain

在批准每条 Shell 命令之前，先了解它的作用。
面向 AI 编码 Agent 的 MCP 服务 · 适用于 Kiro、Cursor、VS Code、Windsurf、Claude Code

English | 中文

快速开始 · 工作原理 · 支持的 IDE · 本地 AI

---

问题

AI 编码 Agent 会在你的机器上运行 Shell 命令。它们会显示批准对话框，但你只能猜：

Agent wants to run:  curl -sL https://raw.githubusercontent.com/some-tool/install.sh | sudo bash

  [ Approve ]   [ Deny ]

安全吗？-sL 是什么意思？为什么要用 sudo？大多数人要么盲目批准（很危险），要么去 Google 搜索（速度慢，还会打断工作流）。

解决方案

cmd-explain 会在每条 Shell 命令运行之前拦截它，并以通俗易懂的语言说明命令作用，同时标注风险等级：

🔴 Transfer data from or to a URL (silent, follow redirects),
   then GNU Bourne-Again SHell
   Risk: high · Source: built-in

Agent wants to run:  curl -sL https://raw.githubusercontent.com/some-tool/install.sh | sudo bash

  [ Approve ]   [ Deny ]

现在你知道了：它会静默下载脚本，并以 root 权限将脚本传给 bash。这是只需一行命令就能植入 rootkit 的途径。拒绝执行很容易——或者至少值得先检查一下。

更多示例

Agent 实际会建议的命令——而这些命令你可能会不假思索地批准：

🔴 chmod -R 777 .
   Change file permissions (recursive)
   Risk: high · Source: built-in
   → Makes every file in your project world-writable

🟡 curl -sL https://install.example.com | bash
   Transfer data from or to a URL (silent, follow redirects),
   then GNU Bourne-Again SHell
   Risk: medium · Source: built-in
   → Downloads and executes a remote script. Classic supply chain risk.

🔴 git push origin main --force
   Upload local commits to a remote (force push, set upstream)
   Risk: high · Source: built-in
   → Overwrites remote history. Other people's commits may be lost.

🔴 rm -rf node_modules dist .next .cache && npm ci
   Remove files or directories (recursive, force without confirmation),
   then clean install from lockfile
   Risk: high · Source: built-in

🟡 npx prisma db push --accept-data-loss
   Run a command from a local or remote npm package without installing
   Risk: medium · Source: built-in
   → That --accept-data-loss flag means exactly what it says.

🔴 kubectl exec -it prod-db-0 -- psql -c "DROP TABLE users"
   Execute a command in a container
   Risk: high · Source: built-in
   → Running SQL directly on a production pod.

每条说明都包含：

• 命令作用：用通俗易懂的语言说明，包括标志和 Shell 模式（2>&1、|| true、>/dev/null）
• 风险等级——低（只读）、中（会改变状态）、高（具有破坏性）或未知
• 来源——built-in（包含 241 条命令的字典）、system（man 手册页）或 ai-generated（大模型）

快速开始

npx cmd-explain setup

就这么简单。它会自动检测你的 IDE、安装 MCP 服务并创建命令前钩子。重启 IDE 后，你就受到保护了。

**要求：**Node.js 18+。无需 API 密钥、无需 Ollama，也无需编辑配置文件。

工作原理

cmd-explain 是一个 MCP 服务，提供一个工具：explain_command。当 Agent 即将运行 Shell 命令时，命令前钩子会自动调用此工具。

说明分为三个层级，按顺序检查：

层级	来源	速度	覆盖范围	需要设置？
1	内置字典——包含 440 多条命令说明，涵盖 240 多个程序（git、docker、npm、kubectl、terraform、aws、brew、cargo 等）	<1ms	约 90% 的 Agent 命令	否
2	系统 man 手册页——解析任意已安装 CLI 工具的 whatis 输出	约 50ms	大多数已安装的工具	否
3	本地 AI——通过 Ollama、OpenAI 或 Anthropic 处理层级 1–2 未覆盖的命令	约 1s	所有命令	可选

层级 1 和 2 完全离线运行，且没有任何依赖。层级 3 需选择启用。

Shell 模式检测

cmd-explain 能理解 Agent 常用的 Shell 语法：

模式	注释
2>&1	将标准错误重定向到标准输出
>/dev/null 2>&1	隐藏所有输出
2>/dev/null	隐藏错误输出
|| true	忽略退出代码
set -e	出错时退出
set -x	执行前打印命令
set -o pipefail	任一管道段出错时都视为失败
$(...)	命令替换

这些内容会附加到说明中，让你始终了解完整命令的作用。

风险分类

等级	含义	示例
🟢 低	只读，没有副作用	ls、cat、grep、git status、curl GET
🟡 中	会改变状态，但可撤销	git commit、npm install、mkdir、docker build
🔴 高	具有破坏性或不可逆	rm -rf、docker rm -f、terraform destroy、find -delete
⚪ 未知	无法识别	自定义/专有 CLI

支持的 IDE

一条安装命令即可完成所有设置。每个 IDE 都会自动使用正确的钩子格式。

IDE	钩子事件	Shell 覆盖范围
Kiro	preToolUse	✅ 所有 Shell 命令
VS Code Copilot	PreToolUse	✅ 所有 Shell 命令
Cursor	beforeShellExecution	✅ 专用 Shell 钩子
Windsurf	pre_run_command	✅ 专用 Shell 钩子
Claude Code	PreToolUse	✅ 通过匹配器

npx cmd-explain setup              # Auto-detect all IDEs
npx cmd-explain setup --ide kiro   # Target one IDE
npx cmd-explain setup --no-hooks   # MCP server only

可选：本地 AI

对于词典或 man 页面中没有的命令，可启用由 Ollama 提供支持的本地 AI 解释（一次性下载约 1 GB）：

brew install ollama
brew services start ollama
ollama pull qwen2.5-coder:1.5b
npx cmd-explain setup --ollama qwen2.5-coder:1.5b

安装命令会验证每个步骤——如果未安装 Ollama 或未拉取模型，它会准确告知你需要运行什么命令。

云 API 也可以使用：

npx cmd-explain setup --openai-key sk-...

支持的提供商：Ollama、OpenAI（OPENAI_API_KEY）、Anthropic（ANTHROPIC_API_KEY）。

手动安装

将以下内容添加到 IDE 的 MCP 配置中：

{
  "mcpServers": {
    "cmd-explain": {
      "command": "npx",
      "args": ["-y", "cmd-explain"]
    }
  }
}

配置文件位置：

• Kiro： .kiro/settings/mcp.json
• VS Code： .vscode/mcp.json
• Cursor： .cursor/mcp.json
• Windsurf： ~/.codeium/windsurf/mcp_config.json
• Claude Code： ~/.claude/settings.json

卸载

npx cmd-explain uninstall

从所有检测到的 IDE 中移除 MCP 配置和钩子文件。彻底移除，不留任何残留。

平台支持

	macOS	Linux	Windows
词典（第 1 层）	✅	✅	✅
Man 页面（第 2 层）	✅	✅	⚠️ 仅 --help
本地 AI（第 3 层）	✅	✅	✅
安装 CLI	✅	✅	✅

许可证

MIT