使用 Python 和 Ollama 构建自动化 CLI 代理
- 作者
- 姓名
- Nino
- 职业
- Senior Tech Editor
大语言模型 (LLM) 的格局已经发生了巨大变化。虽然 GPT-4o 和 Claude 3.5 Sonnet 等云端巨头占据了新闻头条，但一场无声的革命正在开发者的本地机器上发生。随着 Llama 3.1 和 DeepSeek-V3 等高性能开源模型的出现，开发者现在可以构建完全离线运行的复杂 AI 代理 (AI Agents)。然而，本地开发往往只是第一步。为了获得生产级的可靠性和高速推理，许多开发者最终会转向像 n1n.ai 这样的统一 API 聚合平台。
在本教程中，我们将从零开始构建一个功能齐全的 CLI (命令行界面) 代理。该代理不仅能够回答问题，还能执行系统命令、管理文件，并利用 ReAct (推理与行动) 框架进行复杂的逻辑推导。
为什么选择构建本地 CLI 代理？
在深入代码之前，理解本地代理的核心价值至关重要：
- 数据隐私：敏感的系统日志和专有代码永远不会离开您的机器，这对于企业级应用至关重要。
- 零成本：在自己的 GPU/CPU 上运行模型可以消除实验阶段的 Token 费用。
- 低延迟：对于简单的任务，本地推理避免了网络请求的往返时间。
然而，本地硬件终究有其极限。当您的代理需要处理海量的上下文窗口，或者需要 OpenAI o3 等模型提供的顶级推理能力时，切换到 n1n.ai 提供的托管服务可以在不重写核心逻辑的情况下，提供必要的扩展性。
第一步：环境配置
首先，您需要安装 Ollama，它将作为本地推理引擎。从官网下载后，拉取您心仪的模型：
# 拉取模型，建议使用 Llama 3.1 或 DeepSeek-R1 的蒸馏版
ollama pull llama3.1:8b
接下来，配置 Python 环境。我们将使用 ollama 官方 Python 库以及 rich 库来美化终端输出。
pip install ollama rich pydantic
第二步：定义代理架构
一个健壮的 CLI 代理需要一个遵循 ReAct 模式的循环：思考 (Think) -> 行动 (Act) -> 观察 (Observe)。我们将定义一个 CLIAgent 类来管理对话状态和系统交互。
在实现过程中，我们需要特别注意对系统命令的捕获和执行安全。以下是核心代码结构：
import ollama
import subprocess
from rich.console import Console
from rich.markdown import Markdown
console = Console()
class CLIAgent:
def __init__(self, model="llama3.1:8b"):
self.model = model
self.messages = [
{
"role": "system",
"content": "你是一个高效的 CLI 助手。你可以通过将 shell 命令包裹在 <execute> 标签中来执行它们。例如：<execute>ls -la</execute>。请务必在执行前解释你的意图。"
}
]
def run_command(self, command):
# 安全提示：在生产环境中请增加命令白名单校验
try:
result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=30)
return f"标准输出: {result.stdout}\n标准错误: {result.stderr}"
except Exception as e:
return str(e)
def chat(self, user_input):
self.messages.append({"role": "user", "content": user_input})
# 初始推理阶段
response = ollama.chat(model=self.model, messages=self.messages)
content = response['message']['content']
# 解析执行标签
if "<execute>" in content:
# 提取命令逻辑
cmd = content.split("<execute>")[1].split("</execute>")[0]
console.print(f"[bold yellow]正在执行命令:[/bold yellow] {cmd}")
observation = self.run_command(cmd)
self.messages.append({"role": "assistant", "content": content})
self.messages.append({"role": "user", "content": f"观察结果: {observation}"})
# 获取最终推理结果
final_response = ollama.chat(model=self.model, messages=self.messages)
return final_response['message']['content']
return content
第三步：深入理解 ReAct 逻辑与提示工程
在上述代码中，system prompt 是代理的大脑。为了让代理更聪明，我们需要在提示词中加入具体的约束。例如，告诉它如果命令失败了应该如何重试，或者在执行危险命令（如 rm -rf）前必须请求确认。
专家提示：使用本地模型时，JSON 模式的稳定性可能不如闭源模型。如果您发现模型无法正确闭合 <execute> 标签，可以考虑切换到 n1n.ai 上的 DeepSeek-V3，它在指令遵循和格式化输出方面表现极佳。
第四步：处理长上下文与状态管理
随着 CLI 代理执行的命令越来越多，对话历史会迅速膨胀。本地模型通常只有 8k 到 32k 的上下文窗口。一旦超出，模型就会开始遗忘之前的指令。我们可以实现一个简单的上下文压缩算法：
- 监控
self.messages的总 Token 数。 - 当超过阈值时，调用模型对中间的“观察结果”进行摘要提取。
- 保留 System Prompt 和最新的 3 轮对话，替换中间部分为摘要。
第五步：从本地原型到生产环境的跃迁
当您的 CLI 代理逻辑日趋成熟，您可能会遇到以下挑战：
- 算力瓶颈：在笔记本上运行 70B 参数的模型速度极慢。
- 并发限制：本地 Ollama 难以同时处理多个并发请求。
- 模型多样性：某些任务需要 Claude 的代码能力，某些需要 GPT 的逻辑能力。
这时，集成 n1n.ai 是最佳选择。通过 n1n.ai 提供的统一 API 接口，您可以轻松调用全球领先的各类模型，而无需维护复杂的本地环境。
| 维度 | 本地 Ollama | n1n.ai API 聚合 |
|---|---|---|
| 模型支持 | 仅限开源模型 | 涵盖 GPT, Claude, DeepSeek, Gemini |
| 硬件要求 | 高配 GPU/内存 | 无需本地硬件 |
| 稳定性 | 受限于本地进程 | 企业级高可用保障 |
| 开发成本 | 需自行调优 | 开箱即用，按量计费 |
如何在代码中接入 n1n.ai？
由于 n1n.ai 完全兼容 OpenAI SDK，您只需修改几行配置即可完成升级：
from openai import OpenAI
# 将本地 Ollama 替换为 n1n.ai 高速端点
client = OpenAI(
base_url="https://api.n1n.ai/v1",
api_key="您的_N1N_API_KEY"
)
# 现在您可以调用最顶级的 DeepSeek-R1 模型
response = client.chat.completions.create(
model="deepseek-r1",
messages=[{"role": "user", "content": "帮我写一个自动化部署脚本。"}]
)
总结与展望
构建一个基于 Python 和 Ollama 的 CLI 代理是掌握 Agentic Workflow 的绝佳实践。它让您在完全掌控数据的前提下，体验 AI 驱动的自动化能力。然而，技术的发展永无止境，当本地资源无法支撑您的创意时，n1n.ai 将作为您的坚实后盾，提供无限的算力和最前沿的模型支持。
无论您是构建个人效率工具，还是开发企业级自动化平台，从本地起步、通过云端缩放都是最科学的路径。
立即在 n1n.ai 获取免费 API 密钥。