基于Bash的轻量级LLM Agent实现：Dora项目实战解析

最近在探索 LLM Agent 的实现方案时，发现很多框架为了追求功能强大，引入了复杂的依赖和抽象层，导致学习曲线陡峭，部署也略显笨重。如果你只是想快速体验一个能调用系统命令、处理文件、与外部简单交互的智能体，有没有更轻量的选择？今天介绍的Dora项目，或许能给你一个惊喜。它是一个极其精简的 LLM Agent，其核心设计理念是：仅依赖 Bash 作为工具调用层。

本文将带你从零开始，完整拆解 Dora 的设计思想、环境搭建、核心代码解读，并手把手实现一个能与你对话、执行系统命令、管理文件的微型智能体。无论你是想入门 Agent 开发，还是希望为自己的项目添加一个轻量级的自动化助手，这篇文章都能提供一条清晰的实践路径。

1. Dora 是什么？为什么选择“仅 Bash”？

在深入代码之前，我们有必要理解 Dora 项目的定位和其独特的设计哲学。

1.1 核心概念：LLM Agent 与工具调用

LLM（大语言模型）本身是一个强大的文本生成和理解引擎，但它“生活”在数字世界的孤岛中，无法直接操作你的文件系统、运行程序或查询网络。LLM Agent就是为了打破这个孤岛而生的架构。它让 LLM 能够根据对用户指令的理解，自主规划、选择并调用外部工具（Tools）来完成任务，然后将工具执行的结果反馈给 LLM，最终生成对用户有用的回答。

传统的 Agent 框架（如 LangChain、AutoGPT 的早期版本）通常会预定义或允许开发者注册一系列功能各异的工具，例如GoogleSearchTool、PythonREPLTool、FileReadTool等。这些工具本身可能是用 Python、JavaScript 等语言编写的函数或类。

1.2 Dora 的极简主义设计

Dora 项目提出了一个大胆而巧妙的想法：为什么不直接用 Bash Shell 作为所有工具的底层执行环境？

Bash 是 Unix/Linux 系统的默认命令行解释器，它本身就是一个极其强大且完备的“工具调用平台”。通过 Bash，我们可以：

• 执行任何已安装的命令行程序(ls,grep,curl,python,docker等)。
• 进行文件操作(创建、读取、写入、删除、移动文件)。
• 管理进程(启动、停止、查看进程)。
• 进行文本处理(使用sed,awk,cut等)。
• 与操作系统深度交互。

因此，Dora 的核心架构变得异常简单：

1. LLM：负责理解用户意图，并生成需要执行的 Bash 命令。
2. Bash 解释器：作为唯一且统一的工具执行层，运行 LLM 生成的命令。
3. 一个协调循环：将 Bash 执行的结果返回给 LLM，让 LLM 判断任务是否完成，或是否需要下一步操作。

这种设计的优势非常明显：

• 极度轻量：无需为每个功能编写独立的工具函数，大大减少了框架代码。
• 功能无限：理论上，任何能通过命令行完成的任务，Dora Agent 都能尝试去做。
• 学习成本低：开发者只需要理解 LLM 如何与 Bash 交互，无需学习复杂的工具注册和调用框架。
• 易于调试：Agent 的每一步操作都是一个明确的 Bash 命令，执行过程和结果清晰可见。

当然，这也带来了显著的安全风险，因为 LLM 可能会生成破坏性的命令（如rm -rf /）。因此，Dora 的实现必须包含严格的安全沙箱机制，这也是我们后续实战中需要重点解决的部分。

2. 环境准备与核心依赖

在开始构建我们自己的 Dora 之前，需要准备好运行环境。由于 Dora 的核心是 LLM + Bash，因此环境搭建非常直接。

2.1 基础环境要求

• 操作系统：推荐 Linux 或 macOS。Windows 用户可以通过 WSL2、Git Bash 或 Cygwin 获得完整的 Bash 环境。本文示例基于 Ubuntu 22.04 / macOS。
• Python 环境：Dora 的控制逻辑通常用 Python 编写。需要 Python 3.8 或更高版本。
• Bash Shell：确保/bin/bash可用，并且版本较新。

2.2 关键 Python 库

我们将使用openai库来调用大模型 API。当然，你也可以替换为其他兼容 OpenAI API 的本地模型（如通过litellm或ollama）。

# 创建项目目录并进入 mkdir dora-agent && cd dora-agent # 创建虚拟环境（推荐） python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 安装核心依赖 pip install openai

2.3 获取 LLM API 密钥

本文以 OpenAI 的 GPT 模型为例。你需要一个有效的 OpenAI API 密钥。

1. 访问 OpenAI Platform 。
2. 登录后，点击右上角个人头像，选择 “View API keys”。
3. 点击 “Create new secret key” 创建一个新的密钥，并妥善保存。

安全提示：切勿将 API 密钥直接硬编码在代码中或提交到版本控制系统（如 Git）。我们将使用环境变量来管理。

# 在终端中设置环境变量（临时，仅当前会话有效） export OPENAI_API_KEY='你的-api-key-here' # 若要永久设置，可将其添加到 ~/.bashrc 或 ~/.zshrc 文件末尾 echo "export OPENAI_API_KEY='你的-api-key-here'" >> ~/.bashrc source ~/.bashrc

3. Dora 核心原理与架构拆解

理解了“为什么用 Bash”之后，我们来看 Dora Agent 是如何运转的。其核心是一个ReAct (Reasoning + Acting)模式的简化实现。

3.1 工作流程

1. 接收指令：用户提出一个自然语言请求，例如：“帮我找出当前目录下所有扩展名为.log的文件，并统计它们的总行数。”
2. LLM 思考与规划：LLM 分析这个请求，将其分解为一系列可执行的 Bash 命令步骤。它可能会想：“第一步，用find命令列出所有.log文件。第二步，用xargs和wc -l统计行数。”
3. 生成命令：LLM 根据思考，生成具体的 Bash 命令，例如find . -name "*.log" -type f。
4. 执行命令：系统在受控的环境（沙箱）中执行该 Bash 命令。
5. 观察结果：获取命令的标准输出 (stdout) 和标准错误 (stderr)。
6. 判断与循环：LLM 根据执行结果判断任务是否完成。如果未完成（例如，需要基于上一步的结果执行新命令），则回到第 2 步，继续思考和生成下一个命令。
7. 生成最终回答：当 LLM 认为所有必要步骤都已执行并获得了所需信息后，它会综合所有观察结果，生成一个面向用户的、友好的最终回答。

3.2 关键技术：提示工程 (Prompt Engineering)

要让 LLM 稳定地输出 Bash 命令而不是普通对话，并遵循 ReAct 模式，提示词的设计至关重要。一个典型的 Dora 系统提示词可能包含以下部分：

• 角色定义：明确告诉 LLM 它是一个能够使用 Bash 的助手。
• 约束与规则：
  • 只能生成 Bash 命令。
  • 命令必须简单、安全、一次只执行一个清晰的操作。
  • 不能生成需要交互式输入的命令（如rm -i）。
  • 必须等待上一条命令的执行结果后再决定下一步。
• 输出格式：严格规定 LLM 的响应格式，例如使用特定的标记来分隔“思考”、“命令”和“最终答案”。这便于程序自动化解析。
• 安全警告：明确禁止生成危险命令（删除根目录、格式化磁盘、访问敏感文件等）。

4. 完整实战：构建一个安全的微型 Dora Agent

现在，让我们动手实现一个具备基本安全机制的 Dora Agent。我们将创建一个简单的 Python 脚本。

4.1 项目结构

dora-agent/ ├── venv/ # Python 虚拟环境（.gitignore） ├── sandbox.sh # 简单的 Bash 沙箱脚本 ├── dora.py # 主 Agent 逻辑 ├── requirements.txt # 依赖列表 └── README.md

4.2 实现安全沙箱 (sandbox.sh)

安全是重中之重。我们不能让 LLM 生成的命令在宿主机器上肆意运行。一个最简单的沙箱思路是：

1. 在一个临时目录中运行命令。
2. 限制命令的运行用户权限（非 root）。
3. 设置超时，防止死循环命令。
4. 过滤危险命令（黑名单）。

我们先实现一个基础的版本：

#!/bin/bash # 文件：sandbox.sh # 描述：一个简单的命令执行沙箱 set -euo pipefail # 启用严格模式：错误退出、未定义变量报错、管道错误检测 # 定义命令黑名单（正则表达式） DANGEROUS_PATTERNS=( "^rm\s+-rf\s+/\|^rm\s+--no-preserve-root\s+-rf\s+/" # 禁止删除根目录 "^dd\s+.*=/dev/" # 禁止直接操作磁盘设备 "^mkfs\s+" # 禁止格式化 "^:(){:|:&};:" # 禁止 Fork 炸弹 (简化检测) "^\s*>\s*/dev/sd" # 禁止输出到块设备 "^chmod\s+[0-7][0-7][0-7]\s+/" # 禁止修改根目录权限 "^sudo\s+" # 禁止使用 sudo "^su\s+" # 禁止切换用户 ) CMD_TO_RUN="$1" TIMEOUT_SECONDS=10 SANDBOX_DIR=$(mktemp -d) # 创建临时目录作为沙箱工作区 # 检查命令是否在黑名单中 for pattern in "${DANGEROUS_PATTERNS[@]}"; do if echo "$CMD_TO_RUN" | grep -E -q "$pattern"; then echo "[SANDBOX ERROR] Command rejected by security policy: $CMD_TO_RUN" exit 1 fi done echo "[SANDBOX INFO] Running in: $SANDBOX_DIR" cd "$SANDBOX_DIR" || exit 1 # 使用 timeout 命令运行，并捕获输出和错误 # 注意：这里用户是当前用户，更严格的沙箱可以用 `unshare` 或 `docker run` 实现隔离 if output=$(timeout $TIMEOUT_SECONDS bash -c "$CMD_TO_RUN" 2>&1); then # 命令成功或超时前完成 echo "$output" else exit_code=$? if [ $exit_code -eq 124 ]; then echo "[SANDBOX ERROR] Command timed out after ${TIMEOUT_SECONDS} seconds." else echo "[SANDBOX ERROR] Command failed with exit code: $exit_code" echo "$output" # 仍然输出错误信息供 LLM 分析 fi exit $exit_code fi # 清理临时目录（可选，调试时可保留） # trap 'rm -rf "$SANDBOX_DIR"' EXIT

给脚本添加执行权限：

chmod +x sandbox.sh

重要说明：这个沙箱非常基础，主要用于演示和教育目的。在生产环境中，你需要更强大的隔离方案，例如使用 Docker 容器（docker run --read-only --network none alpine sh -c "你的命令"）或专门的沙箱工具（nsjail,bubblewrap）。

4.3 实现 Dora Agent 主逻辑 (dora.py)

这是 Agent 的大脑，负责与 LLM 对话、解析响应、调用沙箱执行命令。

# 文件：dora.py import os import subprocess import sys from openai import OpenAI class DoraAgent: def __init__(self, model="gpt-3.5-turbo", api_key=None): """ 初始化 Dora Agent。 :param model: 使用的 OpenAI 模型。 :param api_key: OpenAI API 密钥。如果为 None，则从环境变量 OPENAI_API_KEY 读取。 """ self.client = OpenAI(api_key=api_key or os.getenv("OPENAI_API_KEY")) if not self.client.api_key: raise ValueError("OpenAI API key not provided. Set OPENAI_API_KEY environment variable.") self.model = model # 系统提示词，定义了 Agent 的角色和行为规范 self.system_prompt = """你是一个名为 Dora 的助手，专门通过执行 Bash 命令来帮助用户解决问题。 你的能力仅限于生成和执行安全的 Bash 命令。你必须严格遵守以下规则： 1. 你只能通过生成 Bash 命令来与外界交互。 2. 每次只生成一条命令。等待该命令执行完成后，根据结果再决定下一步。 3. 命令必须简单、明确，避免使用复杂的管道和嵌套，除非必要。 4. 绝对禁止生成任何危险命令，例如： - 删除系统关键文件或目录（尤其是使用 `rm -rf /` 或类似模式）。 - 修改系统权限、格式化磁盘、执行 fork 炸弹。 - 使用 `sudo` 或尝试提升权限。 - 任何可能造成数据丢失或系统损坏的操作。 5. 如果用户请求无法通过安全的 Bash 命令完成，或者涉及危险操作，你必须礼貌拒绝并解释原因。 6. 你的最终目标是完成任务，并在完成后用自然语言向用户总结你做了什么。 你的输出必须严格遵循以下格式： THOUGHT: [你的思考过程，分析用户请求并规划步骤] COMMAND: [你决定执行的一条 Bash 命令] 或者，当任务完成时： THOUGHT: [你的思考过程，确认任务已完成] FINAL ANSWER: [给用户的最终总结，用友好、自然的语言] 现在，开始帮助用户吧。用户请求如下： """ def execute_command(self, command): """通过沙箱执行 Bash 命令。""" try: # 调用我们编写的沙箱脚本 result = subprocess.run( ["./sandbox.sh", command], capture_output=True, text=True, timeout=15 # 外层再加一个超时控制 ) # 合并 stdout 和 stderr 作为命令输出 output = result.stdout if result.stderr: output += "\n[STDERR]\n" + result.stderr return output.strip(), result.returncode except subprocess.TimeoutExpired: return "[SYSTEM] Command execution timed out.", -1 except Exception as e: return f"[SYSTEM] Failed to execute command: {e}", -1 def run(self, user_query, max_turns=10): """运行 Agent 与用户进行多轮交互。""" messages = [ {"role": "system", "content": self.system_prompt}, {"role": "user", "content": user_query} ] print(f"User: {user_query}") print("-" * 40) for turn in range(max_turns): # 1. 调用 LLM 获取响应 try: response = self.client.chat.completions.create( model=self.model, messages=messages, temperature=0.1, # 低温度，输出更确定 max_tokens=500 ) assistant_message = response.choices[0].message.content except Exception as e: print(f"[LLM ERROR] Failed to get response: {e}") break print(f"Turn {turn+1} - Dora's Response:") print(assistant_message) print("-" * 40) # 2. 解析响应 lines = assistant_message.split('\n') thought = "" command = "" final_answer = "" for line in lines: if line.startswith("THOUGHT:"): thought = line[8:].strip() elif line.startswith("COMMAND:"): command = line[8:].strip() elif line.startswith("FINAL ANSWER:"): final_answer = line[13:].strip() # 3. 如果生成了命令，则执行 if command: print(f"Executing Command: {command}") output, exit_code = self.execute_command(command) print(f"Command Output:\n{output}\n(Exit Code: {exit_code})") print("-" * 40) # 将命令和结果添加到对话历史，供 LLM 下一轮参考 messages.append({"role": "assistant", "content": assistant_message}) messages.append({"role": "user", "content": f"命令 `{command}` 的执行结果如下：\n{output}\n请根据此结果继续思考。"}) # 4. 如果给出了最终答案，则结束 elif final_answer: print(f"Final Answer: {final_answer}") return final_answer else: # 既没有命令也没有最终答案，可能格式错误，结束循环 print("[ERROR] Could not parse THOUGHT/COMMAND/FINAL ANSWER from response.") break print("[INFO] Reached maximum turn limit or encountered an error.") return None if __name__ == "__main__": # 简单的命令行交互 print("=== Dora - The Tiny Bash Agent ===") agent = DoraAgent(model="gpt-3.5-turbo") # 也可使用 "gpt-4" # 示例：处理一个预设任务 # result = agent.run("帮我查看当前目录下有哪些文件和文件夹，并统计总数量。") # 交互模式 while True: try: user_input = input("\nYou (type 'quit' to exit): ").strip() if user_input.lower() in ['quit', 'exit', 'q']: print("Goodbye!") break if user_input: agent.run(user_input) except KeyboardInterrupt: print("\nInterrupted. Goodbye!") break

4.4 运行与验证

1. 确保sandbox.sh和dora.py在同一目录，且sandbox.sh有执行权限。
2. 设置好OPENAI_API_KEY环境变量。
3. 运行 Agent：

python dora.py

你会看到类似以下的交互过程：

=== Dora - The Tiny Bash Agent === You (type 'quit' to exit): 帮我列出当前目录下的所有.txt文件，并计算其中一个文件的行数。 User: 帮我列出当前目录下的所有.txt文件，并计算其中一个文件的行数。 ---------------------------------------- Turn 1 - Dora's Response: THOUGHT: 用户想要做两件事：1) 列出当前目录下的所有.txt文件；2) 计算其中一个文件的行数。我需要分两步进行。首先，使用 `find` 命令列出文件。然后，选择第一个文件并用 `wc -l` 计算行数。 COMMAND: find . -maxdepth 1 -name "*.txt" -type f ---------------------------------------- Executing Command: find . -maxdepth 1 -name "*.txt" -type f Command Output: ./notes.txt ./readme.txt (Exit Code: 0) ---------------------------------------- Turn 2 - Dora's Response: THOUGHT: 找到了两个文件：`./notes.txt` 和 `./readme.txt`。现在我需要计算其中一个文件的行数。我选择第一个文件 `./notes.txt`，使用 `wc -l` 命令。 COMMAND: wc -l ./notes.txt ---------------------------------------- Executing Command: wc -l ./notes.txt Command Output: 42 ./notes.txt (Exit Code: 0) ---------------------------------------- Turn 3 - Dora's Response: THOUGHT: 我已经完成了用户请求的两个步骤：列出了.txt文件，并计算了 `notes.txt` 的行数（42行）。现在可以给出最终答案。 FINAL ANSWER: 我已经完成了您的任务。在当前目录下，我找到了两个 `.txt` 文件：`notes.txt` 和 `readme.txt`。随后，我计算了 `notes.txt` 文件的行数，该文件共有 42 行。 ---------------------------------------- Final Answer: 我已经完成了您的任务。在当前目录下，我找到了两个 `.txt` 文件：`notes.txt` 和 `readme.txt`。随后，我计算了 `notes.txt` 文件的行数，该文件共有 42 行。

4.5 结果说明

通过这个简单的实验，我们成功创建了一个能够理解自然语言任务、自主规划并执行 Bash 命令、最终给出总结的微型 LLM Agent。它展示了 Dora 核心理念的可行性：将复杂的工具调用抽象简化为对 Bash 这一通用接口的调用。

5. 常见问题与排查思路

在实现和运行 Dora Agent 的过程中，你可能会遇到以下问题：

6. 最佳实践与工程建议

将 Dora 从实验玩具变为一个更可靠、可用的组件，需要考虑以下工程化实践：

6.1 安全性强化（重中之重）

1. 使用 Docker 进行强隔离：这是生产环境的黄金标准。为每个命令启动一个全新的、资源受限的、只读的容器。

   # 示例：使用 Docker 沙箱 def docker_execute(command): safe_command = shlex.quote(command) # 注意转义 docker_cmd = [ 'docker', 'run', '--rm', '--network', 'none', # 禁用网络 '--read-only', # 只读根文件系统 '--memory', '256m', # 内存限制 '--cpus', '0.5', # CPU 限制 'alpine:latest', 'sh', '-c', safe_command ] # ... 调用 subprocess ...

2. 白名单机制：与黑名单互补，只允许运行预先审核过的安全命令集合（如ls,find,grep,wc,cat,head,tail等）。对于未知命令，一律拒绝。
3. 用户与权限降级：在沙箱内以非 root、无特权的用户身份运行命令。
4. 审计与日志：记录所有用户查询、LLM 生成的命令、执行结果和系统状态，便于事后审查和问题追踪。

6.2 性能与稳定性优化

1. 会话管理：维护对话上下文，但需要设定合理的 Token 数量上限，避免历史过长导致 API 成本增加和响应变慢。可以只保留最近几轮的交互。
2. 错误处理与重试：对 LLM API 调用和命令执行添加健壮的错误处理（网络超时、速率限制、模型过载等），并实现指数退避的重试机制。
3. 缓存：对于常见的、确定性的查询（如“当前时间”），可以缓存 LLM 的响应或命令结果，避免重复计算和 API 调用。
4. 异步执行：如果支持并发处理多个用户请求，可以使用异步框架（如asyncio）来提高吞吐量。

6.3 提示工程优化

1. 提供示例：在系统提示词中加入少量“少样本示例”（Few-shot Examples），展示从用户问题到THOUGHT/COMMAND/FINAL ANSWER的完整转换过程，能显著提升模型输出的格式稳定性和任务分解质量。
2. 动态上下文：根据当前工作目录、系统环境（如操作系统类型）或之前命令的结果，动态调整提示词，使 LLM 的决策更贴合当前状态。
3. 工具描述：虽然 Dora 使用通用 Bash，但可以在提示词中“描述”一些常用工具的能力和限制，帮助 LLM 更好地选择命令。例如：“你可以使用curl命令从网络获取数据，但注意它可能因网络而失败。”

6.4 可扩展性设计

1. 插件化工具：虽然 Dora 理念是“Only Bash”，但在实际复杂应用中，可以设计一个混合系统。核心仍是 Bash 代理，但允许注册一些用 Python 等语言编写的“高级工具”（如调用特定 API、执行复杂计算）。当用户请求到来时，先由 LLM 判断是否可以使用 Bash 解决，如果不能，则 fallback 到特定的插件工具。这保持了核心的简洁性，又弥补了纯 Bash 的局限性。
2. 配置化：将模型类型、API 端点、超时时间、沙箱策略、允许的命令列表等参数外置到配置文件（如config.yaml）中，便于不同环境下的部署和调整。

Dora 项目的魅力在于其极简哲学和强大的启发性。它剥离了复杂框架的外衣，直指 LLM Agent 的核心——理解、规划与执行。通过亲手实现一个仅依赖 Bash 的微型 Agent，你不仅能深刻理解 ReAct、工具调用等概念，更能体会到在 AI 应用中平衡能力与安全的重要性。

对于初学者，这是一个绝佳的入门项目。你可以在此基础上，尝试增强它的安全性、为它添加记忆功能、或者让它学习使用更复杂的 Bash 组合命令。对于有经验的开发者，Dora 的设计思路可以借鉴到你的业务系统中，作为一个轻量级、高可扩展的自动化模块。

下一步，你可以探索如何将本地开源模型（如通过 Ollama 运行的 Llama 3、Qwen 等）与 Dora 结合，打造一个完全离线、私有的自动化助手。也可以研究如何将 Dora 与图形界面或聊天机器人（如 Telegram Bot、Discord Bot）集成，让更多人能够方便地使用。