# Snow CLI 使用文档——命令注入模式与 Bash 模式 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是命令注入模式和 Bash 模式 Snow CLI 提供了两种命令执行模式，让您可以在对话中直接执行终端命令： ### 命令注入模式（单感叹号 `!`） 命令注入模式允许您在对话消息中直接嵌入命令，由系统自动执行并将结果替换到消息中，然后发送给 AI。这使得 AI 可以在不依赖工具调用的情况下，快速获取命令执行结果，提升交互效率。 ### Bash 模式（双感叹号 `!!`） Bash 模式是一个纯终端模式，执行命令但不发送给 AI。就像一个真正的终端一样，仅执行命令并显示结果，不会触发 AI 对话。适合快速执行命令而不需要 AI 参与的场景。 ## 为什么使用这两种模式 ### 命令注入模式的优势 传统的命令执行方式需要 AI 调用工具，等待用户批准，然后执行命令。命令注入模式提供了更直接的方式： - 在消息中直接嵌入命令，无需额外的工具调用流程 - AI 可以获取实时的系统状态信息 - 适合快速查询和简单操作 - 与敏感命令保护机制集成，确保安全 ### Bash 模式的优势 Bash 模式提供了一个纯粹的终端体验： - 快速执行命令，不触发 AI 对话 - 节省 API 调用成本 - 适合日常终端操作 - 与命令注入模式共享敏感命令保护机制 ## 语法对比 ### 命令注入模式（单感叹号） **基础语法：** ``` !`command` ``` 在消息中使用单感叹号加反引号包裹命令，系统会执行命令并将结果替换到消息中，然后发送给 AI。 **示例：** ``` 检查当前目录：!`pwd` 列出文件：!`ls -la` 查看Git状态：!`git status` ``` **自定义超时时间：** ``` !`command` ``` 在命令后使用尖括号指定超时时间（单位：毫秒）。如果不指定，默认超时时间为 30000 毫秒（30 秒）。 **示例：** ``` !`npm install`<60000> !`docker build .`<120000> !`sleep 5`<10000> ``` ### Bash 模式（双感叹号） **基础语法：** ``` !!`command` ``` 在消息中使用双感叹号加反引号包裹命令，系统会执行命令但不发送给 AI。 **示例：** ``` !!`pwd` !!`ls -la` !!`git status` ``` **自定义超时时间：** ``` !!`command` ``` 语法与命令注入模式相同，支持自定义超时时间。 **示例：** ``` !!`npm install`<60000> !!`docker build .`<120000> !!`sleep 5`<10000> ``` ### 语法规则 **命令注入模式：** - 必须使用完整的 `!` + `` ` `` 组合，缺一不可 - 反引号内为要执行的命令 - 超时时间可选，格式为 `<数字>`，单位毫秒 - 一条消息中可以包含多个命令注入 - 命令按顺序执行 - 执行结果会替换命令语法，然后发送给 AI **Bash 模式：** - 必须使用完整的 `!!` + `` ` `` 组合，缺一不可 - 反引号内为要执行的命令 - 超时时间可选，格式为 `<数字>`，单位毫秒 - 一条消息中可以包含多个命令 - 命令按顺序执行 - 执行结果仅显示，不发送给 AI ## 命令执行流程 ### 命令注入模式流程 当您在消息中使用命令注入语法（单感叹号）时，系统会： #### 1. 解析命令 系统使用正则表达式 `/!`([^`]+)`(?:<(\d+)>)?/g` 解析消息中的所有命令： - 提取命令内容 - 提取超时时间（如果有） - 标记命令在消息中的位置 #### 2. 敏感命令检查 在执行前，系统会检查命令是否匹配敏感命令规则： - 遍历已启用的敏感命令模式 - 如果匹配，弹出确认对话框 - 显示命令内容、匹配模式、风险说明 - 等待用户确认或取消 关于敏感命令配置，请参考：[敏感命令配置](./06.敏感命令配置.md) #### 3. 执行命令 用户确认后（或非敏感命令直接执行）： - Windows 系统使用 `cmd.exe` 执行 - Unix-like 系统（macOS、Linux）使用 `sh` 执行 - 使用当前工作目录作为执行路径 - 继承当前环境变量 - 应用指定的超时时间 #### 4. 收集输出 命令执行期间： - 捕获标准输出（stdout） - 捕获标准错误（stderr） - 记录退出代码 - 检测超时情况 #### 5. 替换消息内容 执行完成后，系统会将原命令语法替换为执行结果： 成功时： ``` --- Command: ls -la --- total 48 drwxr-xr-x 10 user staff 320 Dec 5 10:30 . drwxr-xr-x 20 user staff 640 Dec 4 15:22 .. -rw-r--r-- 1 user staff 1234 Dec 5 10:30 README.md --- End of output --- ``` 失败时： ``` --- Command: invalid-command --- Error: command not found: invalid-command --- End of output --- ``` #### 6. 发送给 AI 替换后的完整消息发送给 AI，AI 可以基于真实的命令输出进行分析和回复。 ### Bash 模式流程 当您在消息中使用 Bash 模式语法（双感叹号）时，系统会： #### 1. 解析命令 系统使用正则表达式 `/!!`([^`]+)`(?:<(\d+)>)?/g` 解析消息中的所有命令： - 提取命令内容 - 提取超时时间（如果有） - 标记命令在消息中的位置 #### 2. 敏感命令检查 与命令注入模式相同，执行前会检查敏感命令规则。 #### 3. 执行命令 执行方式与命令注入模式完全相同。 #### 4. 显示输出 命令执行完成后，结果会显示在终端中，但不会发送给 AI。 #### 5. 终止流程 Bash 模式不会触发 AI 对话，执行完成后流程结束。 ## 使用场景 ### 命令注入模式场景 #### 快速状态查询 ``` 当前目录情况如何？!`ls -la` ``` AI 会看到实际的文件列表，并基于此回答问题。 #### 获取系统信息 ``` 帮我分析系统资源使用： 内存：!`free -h` 磁盘：!`df -h` ``` #### Git 操作查询 ``` 当前分支状态：!`git status` 最近提交：!`git log -5 --oneline` ``` #### 环境检查 ``` 检查Node版本：!`node --version` 检查依赖：!`npm list --depth=0` ``` #### 多命令组合 ``` 项目信息： Git分支：!`git branch --show-current` 未提交更改：!`git status --short` 最近提交：!`git log -1 --oneline` ``` ### Bash 模式场景 #### 快速终端操作 ``` !!`pwd` !!`ls -la` !!`git status` ``` 不触发 AI 对话，仅显示命令执行结果。 #### 日常命令执行 ``` !!`npm run build` !!`git pull` !!`docker ps` ``` 适合不需要 AI 参与的日常操作。 #### 测试命令 ``` !!`echo "Hello World"` !!`date` !!`whoami` ``` 快速测试命令是否正常工作。 ## 安全机制 ### 敏感命令保护 命令注入模式与敏感命令配置完全集成： 1. **自动检测** - 所有命令在执行前都会检查是否匹配敏感模式 - 匹配的命令会触发确认流程 2. **用户确认** - 显示完整的命令内容 - 显示匹配的敏感模式和风险描述 - 显示超时时间（如果有自定义） - 用户可以选择执行或取消 3. **拒绝反馈** - 如果用户拒绝执行敏感命令 - AI 会收到反馈，可能建议替代方案 - 被拒绝的命令不会出现在最终消息中 ### 超时保护 - 默认 30 秒超时防止命令卡死 - 可以为长时间运行的命令自定义超时 - 超时后命令会被强制终止 - 超时信息会反馈给 AI ### 环境隔离 - 命令在当前工作目录执行 - 继承当前 shell 环境变量 - 不会影响 Snow CLI 主进程 - 命令失败不会导致 CLI 崩溃 ## 最佳实践 ### 1. 合理使用命令注入 **适合的场景**： - 快速查询系统状态 - 获取文件列表或内容 - 检查环境配置 - 简单的 Git 操作查询 **不适合的场景**： - 复杂的批量操作（使用工具调用更安全） - 需要交互的命令（如需要输入密码） - 长时间运行的任务（除非设置足够的超时） - 危险的系统操作（应通过工具调用并仔细确认） ### 2. 设置合适的超时时间 根据命令的预期执行时间设置超时： ``` 快速查询（使用默认）：!`pwd` 安装依赖（60秒）：!`npm install`<60000> 构建镜像（120秒）：!`docker build .`<120000> 运行测试（180秒）：!`npm test`<180000> ``` ### 3. 结合上下文使用 给 AI 提供上下文，让它更好地理解命令输出： ``` 我想优化这个项目的依赖，先帮我看看当前安装了哪些包：!`npm list --depth=0` ``` ### 4. 处理敏感命令 对于可能触发敏感命令保护的操作： ``` 请帮我检查是否有未使用的文件可以清理（不要直接删除）：!`git clean -n` ``` 使用安全的查询选项（如 git clean -n），而不是直接执行危险操作。 ### 5. 多命令协作 将相关命令组合在一起，让 AI 获得完整视图： ``` 分析这个分支的情况： 当前分支：!`git branch --show-current` 未合并的提交：!`git log origin/main..HEAD --oneline` 未提交的更改：!`git status --short` ``` ## 常见问题 **Q: 命令注入和工具调用有什么区别？** A: 命令注入会在消息发送给 AI 前执行命令并替换结果，AI 看到的是执行结果。工具调用是 AI 主动请求执行命令，在 AI 响应过程中进行。命令注入更适合快速查询，工具调用更适合复杂操作。 **Q: 为什么我的命令没有执行？** A: 检查以下几点： - 确认语法正确：`!`command`` - 感叹号和反引号必须都存在 - 如果是敏感命令，确认是否在确认对话框中选择了执行 - 查看是否超时（默认 30 秒） **Q: 可以在一条消息中使用多个命令吗？** A: 可以。系统会按顺序执行所有命令，每个命令的结果会替换对应的语法位置。 **Q: 命令执行失败会怎样？** A: 失败的命令会在输出中显示错误信息，AI 会看到完整的错误内容并可能提供解决方案。 **Q: 超时时间最大可以设置多少？** A: 理论上没有上限，但建议不超过 300000 毫秒（5 分钟）。超长运行的任务建议使用工具调用方式，可以更好地监控和管理。 **Q: 命令注入会绕过敏感命令保护吗？** A: 不会。所有通过命令注入执行的命令都会经过敏感命令检查，匹配敏感模式的命令必须经过用户确认。 **Q: 可以注入需要交互的命令吗？** A: 不建议。命令注入不支持交互式输入，这类命令会挂起直到超时。如果需要执行交互式命令，请使用 Snow CLI 的工具调用功能。 **Q: Windows 和 Unix 系统的命令有区别吗？** A: 是的。Windows 使用 `cmd.exe` 执行，Unix-like 系统使用 `sh` 执行。编写命令时需要考虑跨平台兼容性，或者明确指定目标平台。 ## 配置文件位置 命令注入模式本身无需配置，但它依赖敏感命令配置： - Windows: `%USERPROFILE%\.snow\sensitive-commands.json` - macOS/Linux: `~/.snow/sensitive-commands.json` 详细配置方法请参考：[敏感命令配置](./06.敏感命令配置.md) ## 相关功能 - [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令 - [指令面板说明](./09.0.指令面板说明.md) - 了解其他快捷指令功能 - [漏洞猎人模式](./11.漏洞猎人模式.md) - 专业的安全分析功能，也会使用敏感命令保护