Bash4LLM+ 概览：轻量级的 LLM API Bash 包装器

Bash4LLM+ 是一个轻量级、无依赖的 Bash 包装器，旨在与 Groq 的兼容 OpenAI API 以及其他 LLM 提供商进行交互。它允许用户通过单个、可审计的 Bash 脚本直接在命令行上与大型语言模型交互，优先考虑安全性并在类 Unix 环境中实现可移植性。

核心功能与架构

Bash4LLM+ 作为一个自包含脚本运行，仅需要标准的 Unix 工具（bash、coreutils、findutils、util-linux、gawk、curl 和 jq）。它被设计为可在 Linux、macOS、WSL、Cygwin、BSD 以及 Android 上的 Termux 中移植和兼容。

设计即安全

该工具实现了多项安全措施，以确保在单用户环境中的安全性：

• 无 eval 或 /tmp：脚本避免使用 eval，且不使用共享的系统 /tmp 目录，以防止常见的 Shell 漏洞。
• 隔离的临时文件：临时文件存放在用户自定义的 $RUN_TMPDIR 中，并使用受限权限（umask 077）。
• 输出安全：脚本永不执行从 LLM 接收到的输出。
• 权限控制：文件以 600 权限保存，以确保隐私。

UI 状态系统 (ui_state)

Bash4LLM+ 的一个显著特性是其 ui_state 系统。核心脚本将操作元数据以原子 JSON 文件的形式暴露在 $BASH4LLM_CONFIG_DIR/ui_state 中。这使得外部 GUI 或工具（如 Home Assistant）能够在无需解析原始日志的情况下与 CLI 集成。系统跟踪：

• 会话状态：活动会话、消息计数和时间戳。
• API 结果：HTTP 状态、请求 ID 和检测到的边缘情况。
• 提供商能力：活动提供商是否支持流式传输或模型刷新。

会话管理与上下文记忆

Bash4LLM+ 默认不保持记忆。只有在用户显式使用 --session <id> 标志启动会话时，才会启用上下文记忆。

持久历史

当会话处于活动状态时，工具会在 $BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson 中创建一个持久的 NDJSON 文件。该文件存储对话历史，然后发送回 API 以保持上下文。用户可以使用 --session-window [n] 标志控制发送的上下文量，默认值为 10 条消息。

操作使用与命令接口

基本交互

用户可以通过多种方式发送提示：

• 直接提示：./bash4llm "prompt text"
• 管道输入：echo "prompt" | ./bash4llm
• 文件输入：./bash4llm -f prompt.txt
• 多行输入：使用 heredoc（<<'EOF'）。

模型与提供商管理

Bash4LLM+ 通过动态获取提供商 API（例如 GET https://api.groq.com/openai/v1/models）返回的可用模型列表，避免硬编码模型。

• --refresh-models：更新本地模型白名单。
• -m <model>：为单次执行指定模型。
• --set-default <model>：为活动提供商设置持久默认模型。
• --provider <name>：切换 LLM 提供商（可通过 --install-extras 命令安装 Gemini、Hugging Face、Mistral 等额外提供商）。

输出选项

用户可以自定义接收响应的方式：

• 流式：--stream 标志启用实时异步输出。
• JSON 输出：--json 或 --pretty 标志返回 API 的原始或格式化的 JSON 响应。
• 自动保存：脚本会自动保存超过可配置字节阈值（默认 1000 字节）的输出。

技术要求与安装

运行 Bash4LLM+ 的用户必须在 PATH 中安装 bash、coreutils、findutils、util-linux、gawk、curl 和 jq。

安装过程包括克隆仓库、为 bin/bash4llm 脚本添加可执行权限，并导出必要的 API 密钥（例如 export GROQ_API_KEY="your_key"）。可选的额外功能，包括额外的提供商和模板，可通过 ./bash4llm --install-extras 命令进行安装。