MODULE 08 MCP → 你在这里 → 09 CLI

CLI 命令行界面

Agent 的交互面孔——就像终端里的 Claude Code,用文字对话驱动 AI 完成任务

$ python agent_forge.py
 ╔══════════════════════════════════╗
 ║  🤖 AgentForge CLI              ║
 ║  你的 AI 命令行助手            ║
 ╚══════════════════════════════════╝
🤖 AgentForge › 你好,请介绍一下你自己
我是 AgentForge,一个 AI 助手。有什么可以帮你的?
🤖 AgentForge › _
01

什么是 CLI?

CLI(Command Line Interface,命令行界面)是用户与 Agent 交互的文字界面。它就像终端里的 Claude Code——你输入问题或指令,Agent 理解后执行并返回结果。

🍽️

餐厅点餐比喻

你(用户)向服务员(CLI)点菜,服务员传达给厨房(Agent),厨房做好后服务员把菜端给你。

🚗

汽车仪表盘比喻

CLI 就像汽车仪表盘——显示状态信息,接受你的操作指令(加速、刹车、转向),然后控制车辆执行。

🔊

智能音箱比喻

智能音箱是语音界面,CLI 是文字界面——都是连接你和 AI 的桥梁,只是交互方式不同。

为什么选择 CLI?

• 高效:键盘输入比鼠标点击更快
• 可脚本化:可以批量自动化操作
• 资源少:不需要图形界面,服务器也能运行
• 开发者友好:程序员天然习惯终端操作

02

ASCII 艺术横幅

程序启动时显示一个精心设计的 ASCII 艺术横幅(Banner),这是 CLI 的"门面",让用户感受到专业感。

banner.py
def print_banner(self):
    """打印启动横幅"""
    banner = """
 ╔══════════════════════════════════════╗
 ║                                      ║
 ║   🤖  AgentForge CLI  v1.0          ║
 ║   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━     ║
 ║   Your AI Command-Line Assistant     ║
 ║                                      ║
 ║   输入 /help 查看所有命令            ║
 ║   输入问题直接与 AI 对话             ║
 ║                                      ║
 ╚══════════════════════════════════════╝
    """
    # 使用 accent 色打印
    print(Colors.ACCENT + banner + Colors.RESET)

横幅设计要点

• 使用 Box Drawing 字符(╔ ╗ ╚ ╝ ║ ═)绘制边框
• 包含版本号、名称、简短说明
• 用彩色打印,增强视觉效果
• 保持宽度适中(约 40 字符),兼容各种终端

03

命令系统

CLI 支持以 / 开头的内置命令,用于控制程序行为。所有命令分为三大类:

📋 基础命令

命令说明示例
/help显示帮助信息,列出所有可用命令/help
/exit退出程序,显示会话统计/exit
/clear清空终端屏幕/clear
/status查看当前状态(模型、会话信息)/status
/history查看对话历史记录/history
/reset重置对话上下文,开始新对话/reset

⚙️ 配置命令

命令说明示例
/model切换 AI 模型/model gpt-4
/config查看/修改配置项/config set temperature 0.7

🔧 工具命令

命令说明示例
/tools列出所有可用工具/tools
/exec直接执行指定工具/exec read_file path=test.py
04

AgentForgeCLI 核心类

整个 CLI 由一个核心类驱动,它包含 6 个关键方法:

cli.py
class AgentForgeCLI:
    """AgentForge 命令行界面"""

    def __init__(self):
        # 初始化:加载配置、创建 Agent 实例
        self.config = load_config()
        self.agent = Agent(self.config)
        self.history = []
        self.stats = {"turns": 0, "tools": 0}

    def print_banner(self):
        # 打印 ASCII 艺术横幅
        print(BANNER_ART)

    def print_help(self):
        # 显示所有可用命令的帮助信息
        print(HELP_TABLE)

    def run_agent(self, user_input):
        # 将用户输入发送给 Agent,流式输出结果
        response = self.agent.chat(user_input)
        return response

    def process_command(self, cmd):
        # 解析并执行 / 开头的内置命令
        if cmd == "/help":  self.print_help()
        elif cmd == "/exit": self.exit()
        # ... 其他命令

    def run(self):
        # 主入口:启动横幅 → 主循环
        self.print_banner()
        while True:
            user_input = input("🤖 AgentForge › ")
            if user_input.startswith("/"):
                self.process_command(user_input)
            else:
                self.run_agent(user_input)

类设计思路

• 单一职责:CLI 只负责交互,Agent 只负责推理
• 状态管理:history 记录对话,stats 记录统计
• 命令分发:process_command 根据前缀路由到具体方法
• 主循环:run() 方法是程序的心脏,不断"读取-处理-输出"

05

启动流程

当你运行 python agent_forge.py 时,程序按以下步骤启动:

📦 加载配置
config.yaml / .env
→
🎨 打印横幅
ASCII Banner
→
🔑 检查 API Key
无则报错退出
→
🔄 进入主循环
等待用户输入
startup flow
def run(self):
    # Step 1: 打印横幅
    self.print_banner()

    # Step 2: 检查 API Key
    if not self.config.get("api_key"):
        print(Colors.RED + "❌ 未找到 API Key!")
        print("请设置环境变量 OPENAI_API_KEY")
        print("或在 .env 文件中配置")
        return

    # Step 3: 主循环
    print(Colors.GREEN + "✅ 就绪!输入问题开始对话\n")
    while True:
        try:
            user_input = input("🤖 AgentForge › ").strip()
            if not user_input: continue
            if user_input.startswith("/"):
                self.process_command(user_input)
            else:
                self.run_agent(user_input)
        except KeyboardInterrupt:
            print("\n👋 再见!")
            break
06

交互式对话示例

让我们看几个真实场景,感受 CLI 的强大能力:

📁 场景一:文件操作

🤖 AgentForge › 帮我看看当前目录下有哪些 Python 文件
🔧 search_files({"pattern":"*.py","target":"files"})
→ 找到 3 个文件: main.py, utils.py, config.py
找到 3 个 Python 文件:
1. main.py (主程序入口)
2. utils.py (工具函数)
3. config.py (配置文件)
需要我对它们做什么操作吗?

🔍 场景二:代码分析

🤖 AgentForge
🔧 read_file({"path":"main.py"})
→ 读取文件内容 (42 行)
分析结果:
⚠️ 第 15 行: 未处理 FileNotFoundError 异常
⚠️ 第 28 行: 变量 result 可能未定义就使用
✅ 其余部分逻辑正确
需要我帮你修复这些问题吗?

🖥️ 场景三:系统操作

🤖 AgentForge
🔧 exec({"cmd":"df -h"})
→ 命令执行成功
磁盘使用情况:
💿 /dev/disk1: 500GB 总量, 已用 320GB (64%)
💿 剩余空间: 180GB
⚠️ 使用率超过 60%,建议清理大文件

💡 工具调用的可视化

当 Agent 需要使用工具时,CLI 会实时显示调用过程:

🔧 tool_name({...params}) → 工具被调用
→ result → 工具返回结果

这让用户能清楚看到 Agent 的"思考-行动"过程,增强透明度和信任感。

07

配置管理

CLI 的配置遵循优先级链:环境变量 > .env 文件 > 默认值

🌍 环境变量
最高优先级
>
📄 .env 文件
中等优先级
>
⚙️ 默认值
最低优先级
config.py
import os
from dotenv import load_dotenv

def load_config():
    """加载配置,按优先级:env > .env > defaults"""
    load_dotenv()  # 加载 .env 文件

    config = {
        # API Key: 优先从环境变量读取
        "api_key": os.getenv("OPENAI_API_KEY", ""),

        # 模型: 环境变量 > 默认值
        "model": os.getenv("MODEL", "gpt-4"),

        # 温度参数: 环境变量 > 默认值
        "temperature": float(
            os.getenv("TEMPERATURE", "0.7")
        ),
    }

    return config

.env 文件示例

# .env 文件
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
MODEL=gpt-4
TEMPERATURE=0.7
08

🧠 知识测验

检验一下你对 CLI 的理解程度!

1. CLI 是什么的缩写?

Computer Language Interface
Command Line Interface
Code Logic Interpreter

2. 以下哪个是正确的内置命令?

quit()
--help
/help

3. 配置优先级的正确顺序是?

默认值 > .env > 环境变量
环境变量 > .env > 默认值
.env > 环境变量 > 默认值

4. run() 方法的核心是什么结构?

递归调用
while True 主循环
事件驱动

5. 当用户输入不以 / 开头时,CLI 会怎么做?

提示"命令不存在"
忽略输入
将输入发送给 Agent 处理
09

🔬 深入探索

🎨 深入一:ANSI 颜色代码

终端中的颜色通过 ANSI 转义序列 实现。格式为 \033[XXm,其中 XX 是颜色代码。

class Colors:
    """ANSI 颜色代码"""
    RESET   = "\033[0m"    # 重置所有样式
    RED     = "\033[91m"   # 红色 - 错误
    GREEN   = "\033[92m"   # 绿色 - 成功
    YELLOW  = "\033[93m"   # 黄色 - 警告
    BLUE    = "\033[94m"   # 蓝色 - 信息
    MAGENTA = "\033[95m"   # 紫色
    CYAN    = "\033[96m"   # 青色
    BOLD    = "\033[1m"    # 加粗

# 使用示例
print(Colors.GREEN + "✅ 成功!" + Colors.RESET)
print(Colors.RED + "❌ 出错了!" + Colors.RESET)
\033[91m 红色
\033[92m 绿色
\033[93m 黄色
\033[94m 蓝色
\033[95m 紫色
\033[96m 青色

⚠️ 注意:不是所有终端都支持 ANSI 颜色。Windows 旧版 cmd.exe 可能需要额外设置。现代终端(Terminal.app、iTerm2、VS Code)默认支持。

🛡️ 深入二:输入验证与安全

用户输入是不可信的,CLI 需要做严格的验证:

def process_command(self, cmd):
    """安全地处理用户命令"""
    cmd = cmd.strip().lower()

    # 1. 空命令检查
    if not cmd:
        return

    # 2. 命令白名单(只允许已知命令)
    valid_commands = {
        "/help", "/exit", "/clear",
        "/status", "/history", "/reset",
        "/model", "/config", "/tools", "/exec"
    }
    base_cmd = cmd.split()[0]

    if base_cmd not in valid_commands:
        print(f"❌ 未知命令: {base_cmd}")
        print("输入 /help 查看可用命令")
        return

    # 3. 参数长度限制
    if len(cmd) > 1000:
        print("❌ 输入过长")
        return

    # 4. 执行命令 ...

关键原则:白名单验证(只接受已知命令)、长度限制(防止溢出)、参数消毒(过滤危险字符)。

🔧 深入三:工具调用可视化

当 Agent 决定使用工具时,CLI 需要以友好的方式展示这个过程:

def display_tool_call(tool_name, params, result):
    """可视化工具调用"""

    # 1. 显示调用(橙色)
    print(Colors.YELLOW +
          f"🔧 {tool_name}({json.dumps(params)})" +
          Colors.RESET)

    # 2. 显示结果(绿色/红色)
    if result["success"]:
        print(Colors.GREEN +
              f"  → ✅ {result['summary']}" +
              Colors.RESET)
    else:
        print(Colors.RED +
              f"  → ❌ {result['error']}" +
              Colors.RESET)

    # 3. 更新统计
    self.stats["tools"] += 1

这种可视化让用户能实时看到 Agent 的行动,而不是只看到最终答案。这建立了信任——你知道 AI 做了什么、用了什么工具、结果如何。

10

📝 本章总结

🎯 你学到了什么

🚀 最佳实践

• 清晰的提示词:告诉 Agent 你想要什么,越具体越好
• 分步执行:复杂任务拆成小步骤,逐步完成
• 善用命令:用 /status 检查状态,用 /history 回顾对话
• 关注工具调用:观察 Agent 用了什么工具,确认方向正确
• 及时重置:话题切换时用 /reset 清理上下文