cmd-agent

🤖 从零构建一个命令行 AI Agent — 两种实现方式，一份实战教程。

cmd-agent 是一个教学项目，通过构建一个真实可用的命令行 AI 助手，展示 LLM Agent 的核心原理和两种主流实现方式。

你只需要用自然语言描述任务，AI 会自动规划步骤、生成 Shell 命令、执行并观察结果，直到任务完成。不需要记住复杂的命令语法，不需要翻 man page，只需要 ask。

✨ 特性

• 🧠 Agent 模式 — AI 自主推理、执行、观察，多步完成复杂任务
• 💬 交互模式 — 进入 REPL 对话，保留上下文连续提问
• 🌍 智能上下文感知 — 自动检测项目类型、Git 状态、目录结构、运行时版本等，生成更精准的命令
• 🔌 多提供商支持 — 支持 Kimi、DeepSeek 等 OpenAI 兼容 API
• 🛡️ 安全优先 — 每条命令执行前都需要用户确认

📦 安装

npm install -g .

🚀 使用

# Agent 模式 — 给定任务，AI 自主推理执行
ask "检查磁盘使用情况并清理 /tmp 下超过 100MB 的文件"
ask "ssh 到 earth 服务器检查 nginx 是否运行"

# 交互模式 — 无参数启动，进入 REPL 对话
ask

⚙️ 配置

环境变量	说明	默认值
ASK_PROVIDER	AI 提供商（kimi / deepseek）	kimi
ASK_API_KEY	API 密钥	—

🏗️ 两种 Agent 实现

本项目包含 两种独立的 Agent 架构实现，展示了 LLM Agent 从经典到现代的演进：

src-react/ — 文本解析版（ReAct 范式）

经典的 Reasoning + Acting 架构。通过 Prompt 约束 AI 按 THOUGHT → ACTION → OBSERVATION 的固定文本格式输出，代码端用正则表达式解析提取命令。

优点：兼容任意 LLM（包括本地 Ollama 模型），无需 Function Calling 支持
缺点：依赖 AI 遵守文本格式，需要防御性解析代码

src-fc/ — Function Calling 版

现代的 结构化工具调用 架构。通过 OpenAI tools API 定义工具（run_command / finish），AI 返回结构化 JSON 而非自由文本，API 层保证格式正确性。

优点：零解析代码，格式由协议层保证，易于扩展新工具
缺点：要求 AI 提供商支持 Function Calling

两种实现的 Agent 循环本质相同——思考 → 行动 → 观察 → 重复，区别仅在于 AI 如何表达意图以及代码如何理解意图。

许可证

MIT