一个基于 Go 语言的 AI Agent，通过自然语言交互来管理和监控 Arch Linux 系统。
- 🔧 系统管理：pacman/yay 包管理、systemd 服务管理
- 📊 系统监控：CPU/内存/磁盘监控、进程监控
- 📝 日志分析：systemd 日志查询和分析
- 🤖 智能助手：基于 OpenAI GPT 的自然语言交互
- 💬 流式输出：实时显示 AI 响应
- 📚 对话历史：完整的对话上下文管理
- ⚡ 工具懒加载：按需加载工具，减少启动时间和 token 消耗
go install github.com/npc1607/arch-linux-agent@latest# 交互模式（默认启用流式输出）
arch-agent chat
# 单次命令
arch-agent ask "检查系统状态"
# 禁用流式输出
arch-agent chat --no-stream
# 安全模式（只读操作）
arch-agent chat --safe-mode在交互模式中，可以使用以下特殊命令：
help,?- 显示帮助信息clear,cls- 清空对话历史history- 查看对话历史stream- 切换流式输出模式exit,quit- 退出程序
┌─────────────────────────────────────────────────────────────┐
│ CLI Layer │
│ - 命令行解析 (cobra) │
│ - 配置管理 (viper) │
│ - 用户交互 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ Chat Session │
│ - 会话管理 │
│ - 流式输出 / 普通输出 │
│ - 对话历史管理 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ Agent Core │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Mode Selection (Function Calling / Planner) │ │
│ └──────────────┬──────────────────────────┬──────────────┘ │
│ │ │ │
│ ┌──────────────▼──────┐ ┌───────────▼──────────────┐ │
│ │ Function Calling │ │ Planner Mode │ │
│ │ (默认模式) │ │ (任务规划模式) │ │
│ └──────────────┬──────┘ └───────────┬──────────────┘ │
└─────────────────┼──────────────────────────┼────────────────┘
│ │
┌───────────▼──────────┐ ┌───────────▼────────────┐
│ LLM Client │ │ Rule-Based Planner │
│ (OpenAI GPT) │ │ (LLM Fallback) │
└───────────┬──────────┘ └───────────┬────────────┘
│ │
┌───────────▼──────────────────────────▼────────────┐
│ Lazy Tool Registry (按需加载) │
│ ┌──────────────────────────────────────────────┐ │
│ │ 关键词检测 → 自动触发 → 工具组加载 │ │
│ │ - pacman (包管理) - systemd (服务管理) │ │
│ │ - monitor (监控) - log (日志分析) │ │
│ │ - weather (天气) │ │
│ └──────────────────┬───────────────────────────┘ │
└─────────────────────┼───────────────────────────────┘
│
┌─────────────────────▼───────────────────────────────┐
│ Tool Registry (核心工具) │
│ 基础工具 + 已加载的懒加载工具 │
└─────────────────────┬───────────────────────────────┘
│
┌─────────────────────▼────────────┐
│ Shell Executor │
│ - 命令执行 │
│ - 安全验证 │
└──────────────────────────────────┘
这是 Agent 的主要工作模式，使用 OpenAI 的 Function Calling 机制：
用户输入
│
▼
┌─────────────────────────────────────────┐
│ 1. 构建系统提示词 │
│ - 角色定义 │
│ - 可用工具列表 │
│ - 安全规则 │
└────────────────┬────────────────────────┘
│
┌────────────▼────────────┐
│ 2. 添加到对话历史 │
│ messages.append(user) │
└────────────┬────────────┘
│
┌────────────▼────────────────────────┐
│ 3. 调用 LLM（带工具定义） │
│ - 传递对话历史 │
│ - 传递工具列表 │
└────────────┬────────────────────────┘
│
┌────────────▼────────────┐
│ 4. LLM 决策 │
│ ┌─────────────────┐ │
│ │ 需要工具？ │ │
│ └──┬───────────┬──┘ │
│ 是 │ 否 │
│ │ │ │
│ ┌────▼───┐ ┌──▼───┐ │
│ │执行工具│ │直接回复│ │
│ └────┬───┘ └──┬───┘ │
└───────┼──────────┼──────┘
│ │
│ ┌─────▼─────┐
│ │ 5. 返回结果│
│ │ 保存历史 │
│ └───────────┘
│
┌───────▼──────────────────┐
│ 6. 执行工具调用 │
│ - 解析工具参数 │
│ - 验证安全性 │
│ - 执行 Shell 命令 │
│ - 格式化输出 │
└───────┬──────────────────┘
│
┌───────▼──────────────────┐
│ 7. 让 LLM 总结工具结果 │
│ - 传递工具输出 │
│ - 生成自然语言回复 │
└───────┬──────────────────┘
│
┌───────▼──────────────────┐
│ 8. 返回最终回复 │
│ - 流式输出（实时） │
│ - 或完整输出（等待） │
└───────────────────────────┘
示例：
🤖 You> 安装 nginx
🤖 Agent> [Function Calling]
1. LLM 决策：调用 pacman_install
2. 执行工具：sudo pacman -S nginx
3. 工具结果：安装成功
4. LLM 总结：nginx 已成功安装...用于复杂任务的多步骤规划：
用户输入
│
▼
┌─────────────────────────────────────────┐
│ 1. 任务规划 │
│ - LLM 分析意图 │
│ - 生成执行计划 │
│ - 分解为步骤 │
│ ┌─────────────────────────────────┐ │
│ │ Intent: package_manage │ │
│ │ Steps: │ │
│ │ 1. pacman_search nginx │ │
│ │ 2. pacman_install nginx │ │
│ │ 3. systemd_enable nginx │ │
│ └─────────────────────────────────┘ │
└────────────────┬────────────────────────┘
│
┌────────────▼────────────┐
│ 2. 逐步执行计划 │
│ ┌──────────────────┐ │
│ │ Step 1: Search │ │
│ │ ✓ 完成 │ │
│ ├──────────────────┤ │
│ │ Step 2: Install │ │
│ │ ⚠ 需要确认 │ │
│ ├──────────────────┤ │
│ │ Step 3: Enable │ │
│ │ ▶ 待执行 │ │
│ └──────────────────┘ │
└────────────┬────────────┘
│
┌────────────▼────────────┐
│ 3. 汇总结果 │
│ - LLM 总结执行结果 │
│ - 生成最终回复 │
└─────────────────────────┘
示例：
🤖 You> 帮我安装并配置 nginx
🤖 Agent> [Planner Mode]
📋 任务类型: 包管理
📝 任务描述: 安装并配置 nginx
⏱️ 预计耗时: 75 秒
执行步骤:
1. 搜索 nginx 包
2. 安装 nginx ⚠️ 此操作需要确认
3. 启用 nginx 服务 ⚠️ 此操作需要确认
[正在执行...]
✅ 所有步骤已完成
nginx 已成功安装并配置为开机自启。Agent 通过工具注册表管理 15+ 个系统工具：
// 工具定义
type Tool struct {
Name string // 工具名称
Description string // 工具描述
Function openai.FunctionDefinition // OpenAI 函数定义
Handler ToolHandler // 执行函数
Safe bool // 是否安全（只读）
}
// 工具分类
安全工具（只读）:
- pacman_search // 搜索包
- pacman_query // 查询包信息
- systemd_status // 查看服务状态
- monitor_cpu // CPU 监控
- monitor_memory // 内存监控
- monitor_disk // 磁盘监控
- log_errors // 错误日志
- log_service // 服务日志
不安全工具（需确认）:
- pacman_install // 安装包
- systemd_start // 启动服务
- systemd_stop // 停止服务
- systemd_restart // 重启服务工具调用流程：
LLM 决策调用工具
│
▼
┌───────────────────────────────────┐
│ ToolRegistry.Execute() │
│ 1. 检查工具是否存在 │
│ 2. 检查安全模式 │
│ - SafeMode + 不安全工具 → 拒绝 │
│ 3. 解析工具参数 │
└───────────────┬───────────────────┘
│
┌───────────▼──────────┐
│ Shell Executor │
│ 1. 命令验证 │
│ 2. 超时控制 │
│ 3. 执行命令 │
│ 4. 捕获输出 │
└───────────┬──────────┘
│
┌───────────▼──────────┐
│ 格式化输出 │
│ - 结构化数据 │
│ - 人类可读格式 │
└───────────┬──────────┘
│
┌───────────▼──────────┐
│ 返回给 LLM │
│ 用于生成最终回复 │
└──────────────────────┘
Agent 实现了基于关键词的智能工具懒加载系统，大幅减少启动时间和 token 消耗。
用户输入: "帮我安装 nginx"
│
▼
┌─────────────────────────────────────┐
│ 1. 关键词检测 │
│ - 检测到 "安装" → pacman 组 │
│ - 检测到 "nginx" → 包名 │
└──────────────┬──────────────────────┘
│
┌──────────▼──────────┐
│ 2. 自动触发加载 │
│ ┌─────────────────────────────────┐ │
│ │ 加载 pacman 工具组 (4个工具) │ │
│ │ - pacman_search │ │
│ │ - pacman_query │ │
│ │ - pacman_install │ │
│ │ - pacman_check_updates │ │
│ └─────────────────────────────────┘ │
└────────────┬─────────────────────┘
│
┌────────────▼────────────┐
│ 3. 工具立即可用 │
│ - 注册到 ToolRegistry │
│ - LLM 可以调用 │
└────────────┬─────────────┘
│
┌────────────▼────────────┐
│ 4. 执行用户请求 │
│ LLM 调用 pacman_install│
└─────────────────────────┘
| 工具组 | 关键词 | 工具数量 | 说明 |
|---|---|---|---|
| pacman | 包、软件、安装、pacman、install | 4 | 包管理工具 |
| systemd | 服务、systemd、启动、停止 | 5 | 服务管理工具 |
| monitor | 监控、CPU、内存、磁盘 | 4 | 系统监控工具 |
| log | 日志、log、错误、调试 | 2 | 日志分析工具 |
| weather | 天气、weather、温度 | 1 | 天气查询工具 |
| 模式 | 启动时间 | 初始 Token | 工具数量 |
|---|---|---|---|
| 传统模式 | ~2-3秒 | ~150k | 全部预加载 |
| 懒加载模式 | < 1秒 | ~20k | 按需加载 |
| 改善 | 70%+ ↓ | 90%+ ↓ | - |
- 快速启动 - 只加载核心工具，启动时间减少 70%+
- 节省资源 - Token 消耗减少 90%+，降低 API 成本
- 智能触发 - 关键词自动识别，无需手动加载
- 用户友好 - 自动确认机制，透明加载过程
- 灵活扩展 - 轻松添加新的工具组
懒加载模式已默认启用，无需额外配置：
# 启用懒加载（默认）
arch-agent chat
# 使用传统模式
# 修改 internal/chat/session.go:
# ag, err := agent.NewAgent(config)详见：
支持两种输出模式：
流式输出（默认）：
用户: 介绍你自己
Agent: 我是一个...（逐字显示）
专业的...（继续显示）
Arch Linux...（继续显示）
系统管理助手（完成）
完整输出（--no-stream）：
用户: 介绍你自己
Agent: （等待...）
我是一个专业的 Arch Linux 系统管理助手
（完整响应一次性显示）
对话历史存储结构：
[]Message{
{Role: "system", Content: "系统提示词"},
{Role: "user", Content: "检查系统"},
{Role: "assistant", Content: "系统正常..."},
{Role: "user", Content: "查看内存"},
{Role: "assistant", Content: "总内存 16G..."},
}
管理命令：
- history // 查看格式化历史
- clear // 清空历史
// Shell 执行器会检查：
- 命令注入（&&, ||, |）
- 重定向（>, <）
- 后台运行（&）
- 危险命令（rm -rf /）# 启用安全模式
arch-agent chat --safe-mode
# 效果：
- 只能执行安全工具（只读操作）
- 安装、启动服务等操作被拒绝
- 查询、监控操作正常Safe = true: // 查询类工具，无需确认
Safe = false: // 修改类工具，需要用户确认配置文件位于 ~/.config/arch-agent/config.yaml
llm:
api_key: "your-openai-api-key"
model: "gpt-4"
base_url: ""
max_tokens: 2000
temperature: 0.7
security:
safe_mode: false
confirm_before_action: true
logging:
level: "info"
output: "stdout" # stdout, file, both
file: "/var/log/arch-agent.log"
memory:
enabled: false # 记忆系统未实装
path: "~/.local/share/arch-agent/memory"
⚠️ 注意：记忆系统已设计完成，但尚未实装到 Agent。
记忆系统将提供以下功能：
-
Token 级记忆
- 对话历史管理 ✅（已实现）
- 自动总结机制（未实现）
- 上下文压缩（未实现）
-
Latent 级记忆
- 向量存储（未实现）
- 语义检索（未实现）
- RAG 增强（未实现）
-
记忆持久化
- 历史记录保存（未实现）
- 经验学习（未实现）
- 跨会话记忆（未实现）
当前状态：
- ✅ 内存对话历史已实现
- ⏳ 向量数据库集成待开发
- ⏳ RAG 注入待开发
- ⏳ 记忆持久化待开发
详见 .dev_history/2025-03-19_memory-system-design.md
✨ 新功能：基于 Claude Code MCP Tool Search 实现的工具懒加载系统
- ⚡ 快速启动 - 启动时间从 2-3秒 减少到 < 1秒
- 💾 节省资源 - Token 消耗从 150k 减少到 20k（90%+ 改善）
- 🎯 智能触发 - 关键词自动识别并加载相关工具
- 🔒 安全可控 - 用户确认机制，透明加载过程
- 📊 状态可见 - 实时查看工具组加载状态
| 工具组 | 关键词 | 工具 | 说明 |
|---|---|---|---|
| pacman | 包、软件、安装 | 4 | 包管理 |
| systemd | 服务、启动、停止 | 5 | 服务管理 |
| monitor | CPU、内存、磁盘 | 4 | 系统监控 |
| log | 日志、错误 | 2 | 日志分析 |
| weather | 天气、温度 | 1 | 天气查询 |
用户输入 → 关键词检测 → 自动触发 → 工具组加载 → 执行操作
示例：
👤 You> 帮我安装 git
[系统检测到 "安装" 关键词]
[自动加载 pacman 工具组...]
[加载完成，4 个工具可用]
🤖 Agent> 我将为您安装 git 软件包...
[执行 pacman_install]
✅ 安装完成懒加载模式已默认启用，无需额外配置。如需调整：
- 查看工具状态：
status := agent.GetLazyRegistryStatus()
fmt.Println(agent.FormatLazyToolsStatus(status))- 手动加载工具组：
tools, err := agent.LoadToolGroup(ctx, "monitor", true)- 切换到传统模式：
// 在 internal/chat/session.go 中修改
ag, err := agent.NewAgent(config) // 传统模式
// ag, err := agent.NewAgentWithLazyLoading(config, true) // 懒加载模式- 📖 工具懒加载详细文档 - 完整的实现说明
- 📖 Agent 集成指南 - 使用指南和示例
- 💡 Claude Code MCP Tool Search - 设计灵感来源
详见 PLAN.md 和 .dev_history/ 目录
MIT