# ops-agent

**Repository Path**: timepang/ops-agent

## Basic Information

- **Project Name**: ops-agent
- **Description**: 服务器运维AI助手
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpsAgent - AI 运维助手

终端内运行的 AI 运维助手，用自然语言描述需求，自动执行命令并分析结果。

## 特性

- **自然语言交互** - 用中文描述运维需求，自动生成并执行命令
- **精简输出** - 内置 response-format Skill，固定输出格式：结论 → 数据 → 建议
- **安全防护** - 4 级命令安全分级（只读/低风险/高风险/禁止），危险操作需确认
- **Skill 扩展** - 通过 YAML 文件自定义运维 Skill，沉淀领域经验
- **终端友好** - 异步执行命令，完成后立即释放终端，不占用 TTY
- **多 LLM 后端** - 支持 DashScope / OpenAI / DeepSeek / Ollama 等

## 快速开始

### 1. 安装

```bash
cd ops-agent
uv sync                        # 安装依赖，创建 .venv 和 uv.lock
```

### 2. 配置 API Key

```bash
# 方式一：环境变量（推荐）
export DASHSCOPE_API_KEY="your-api-key"

# 方式二：命令行参数
uv run ops-agent --api-key your-api-key

# 方式三：配置文件（见下方）
```

### 3. 启动

```bash
uv run ops-agent
```

### 4. 使用

```
你> 看看磁盘使用情况

  ⚡ 执行: df -h

╭─ 分析结果 ─────────────────────────────────╮
│ ## 结论                                     │
│ /data 分区使用率 90%，需要关注。              │
│                                             │
│ ## 关键数据                                  │
│ | 分区   | 使用率 | 状态    │                │
│ |--------|--------|---------|                │
│ | /      | 85%    | 正常    │                │
│ | /data  | 90%    | ⚠️ 偏高 │                │
│                                             │
│ ## 建议操作                                  │
│ 1. 定位大文件: du -sh /data/* | sort -rh    │
│ 2. 清理旧日志: find /var/log -name "*.gz"   │
│    -mtime +7 -delete                        │
╰─────────────────────────────────────────────╯

你> │  ← 终端立即释放
```

## 配置

### 配置文件

首次运行前，复制示例配置：

```bash
mkdir -p ~/.ops-agent
cp config.example.yaml ~/.ops-agent/config.yaml
# 编辑 config.yaml 填入你的 API Key 等配置
```

### 配置项说明

```yaml
llm:
  provider: openai_compatible      # LLM 提供者
  model: qwen-plus                 # 模型名称
  api_key: "${DASHSCOPE_API_KEY}"  # API Key（支持环境变量引用）
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  temperature: 0.1                 # 低温度保证命令生成确定性
  max_tokens: 4096

executor:
  default_timeout: 30              # 命令超时（秒）
  max_output_chars: 50000          # 最大输出捕获字符数
  shell: "/bin/bash"

safety:
  level: normal                    # strict | normal | permissive
  auto_confirm: false              # L0 命令是否自动确认
  blocked_commands:                # 额外禁止的命令（正则）
    - "mkfs.*"

display:
  theme: monokai
  max_display_lines: 100
  show_command: true
```

### 多平台多模型自动降级

按平台分组配置多个模型。先在当前平台内尝试所有模型，全部不可用时整体切换到下一个平台：

```yaml
llm:
  models:
    # 平台 1：阿里云百炼
    - base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
      api_key: "${DASHSCOPE_API_KEY}"
      models:
        - qwen-plus
        - qwen-turbo

    # 平台 2：DeepSeek（百炼全部模型额度用完时切换）
    - base_url: "https://api.deepseek.com/v1"
      api_key: "${DEEPSEEK_API_KEY}"
      models:
        - deepseek-v3

    # 平台 3：本地 Ollama（离线兜底）
    # - base_url: "http://localhost:11434/v1"
    #   api_key: "ollama"
    #   models:
    #     - qwen2.5
```

- 每个平台组继承顶层 `base_url`/`api_key`，也可单独覆盖
- 未配置 `api_key` 的平台组自动跳过（不会误用其他平台的 key）
- 切换后"记住"当前可用平台，后续请求不再尝试已耗尽的平台
- 平台内模型逐个尝试，全部失败才切换到下一个平台
- 日志记录每次切换原因

### 命令行参数

```bash
ops-agent [选项]

选项：
  -c, --config PATH     配置文件路径（默认 ~/.ops-agent/config.yaml）
  --daemon              启动后台守护进程
  --stop                停止后台守护进程
  --status              查看守护进程状态
  --chat INPUT          发送单次请求到守护进程（用于 hook/脚本调用）
  --dry-run             Dry-run 模式（只生成命令不执行）
  --safe LEVEL          安全级别（strict/normal/permissive）
  --model MODEL         LLM 模型名称
  --api-key KEY         LLM API Key
  --base-url URL        LLM API base URL
```

### 切换 LLM 后端

```bash
# 阿里云 DashScope（默认）
uv run ops-agent --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --model qwen-plus

# OpenAI
uv run ops-agent --base-url https://api.openai.com/v1 --model gpt-4o --api-key sk-xxx

# DeepSeek
uv run ops-agent --base-url https://api.deepseek.com/v1 --model deepseek-chat

# Ollama 本地
uv run ops-agent --base-url http://localhost:11434/v1 --model llama3 --api-key ollama
```

## 后台守护进程模式

Agent 可以作为后台服务运行，通过终端钩子自动响应中文输入。

### 启动与停止

```bash
# 启动后台守护进程
make daemon
# 或
uv run ops-agent --daemon

# 查看状态
make status
# 或
uv run ops-agent --status

# 停止
make stop
# 或
uv run ops-agent --stop
```

### 安装终端钩子

```bash
# 安装钩子文件到 ~/.ops-agent/
make hook

# 在 ~/.bashrc 中添加
source ~/.ops-agent/hook.sh
```

安装后，终端行为：

| 输入 | 行为 |
|------|------|
| `ls -la` | 正常执行命令 |
| `docker ps` | 正常执行命令 |
| `echo 中文输出` | 正常执行命令（输出含中文不影响） |
| `查看磁盘` | 自动转发给 Agent 处理 |
| `服务器状态` | 自动转发给 Agent 处理 |

**规则**：只有以中文字符开头的输入才会触发 Agent，其他一切正常执行。

### 误触发防护

Agent 通过 bash 的 `DEBUG` trap 检查 `BASH_COMMAND`（用户输入的命令），而非命令输出。因此：

- `echo 中文输出` — 命令以 `e` 开头，正常执行
- `grep 错误 log.txt` — 命令以 `g` 开头，正常执行
- `docker ps 查看容器` — 命令以 `d` 开头，正常执行
- `查看磁盘` — 命令以 `查` 开头，触发 Agent

运行 `make test-hook` 验证 20 个测试用例。

### 钩子管理命令

```bash
ops-agent-start     # 启动守护进程
ops-agent-stop      # 停止守护进程
ops-agent-status    # 查看状态和内存占用
```

### 内存管理

守护进程自动管理内存：

- 最多 20 个同时活跃会话
- 空闲 30 分钟自动清理会话
- 每个会话保留最近 10 轮对话，超出自动裁剪
- 通过 `ops-agent-status` 查看内存占用

## Skill 系统

### 什么是 Skill

Skill 是可插拔的能力单元，封装了特定场景的命令序列和分析逻辑。

**内置 Skill**（始终生效，不可覆盖）：
- `response-format` - 强制输出格式：结论 → 数据 → 建议
- `safety-guard` - 安全规则注入
- `command-router` - 命令路由与分级
- `context-manager` - 上下文记忆管理

**用户自定义 Skill** - 通过 YAML 文件扩展

### 创建自定义 Skill

```bash
# 1. 确保 skills 目录存在
mkdir -p ~/.ops-agent/skills

# 2. 复制模板
cp src/ops_agent/skills/templates/default.yaml ~/.ops-agent/skills/my-skill.yaml

# 3. 编辑 Skill 定义
vim ~/.ops-agent/skills/my-skill.yaml
```

### Skill YAML 格式

```yaml
name: k8s-diagnose
description: "Kubernetes 集群故障诊断"
version: "1.0"

# 触发条件
triggers:
  keywords: ["k8s", "kubernetes", "pod", "容器", "集群"]
  intent: "kubernetes 相关的诊断和排查"

# 执行步骤（可选，不定义则 LLM 自主规划）
steps:
  - name: "检查节点状态"
    command: "kubectl get nodes -o wide"
    on_failure: "stop"           # stop=停止 | continue=继续

  - name: "检查异常 Pod"
    command: "kubectl get pods --all-namespaces | grep -v Running"
    on_failure: "continue"

# 分析提示词（告诉 LLM 如何分析输出）
analysis_prompt: |
  分析以上 K8s 集群状态，重点关注：
  1. 节点是否有 NotReady 状态
  2. Pod 是否有 CrashLoopBackOff / Error / Pending
  只报告异常项。
```

### Skill 匹配规则

- 用户输入匹配 Skill 的 `keywords` 或 `intent` 时自动激活
- 同一时刻最多激活 2 个 Skill（避免 prompt 过长）
- 可通过 `/skill <name>` 手动指定

### Skill 管理命令

```
/skill list          列出所有 Skill（内置 + 自定义）
/skill <name>        手动指定使用某个 Skill
/reload              重新加载配置和 Skill
```

## 交互命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助信息 |
| `/history` | 查看历史操作记录 |
| `/dry-run` | 切换 dry-run 模式（只生成命令不执行） |
| `/safe strict` | 切换到严格安全模式 |
| `/safe normal` | 切换到普通安全模式 |
| `/safe permissive` | 切换到宽松安全模式 |
| `/skill list` | 列出所有 Skill |
| `/reload` | 重新加载配置和 Skill |
| `/exit` | 退出 Agent |
| `Ctrl+C` | 中断当前操作 |
| `Ctrl+D` | 退出 Agent |

## 安全机制

### 命令分级

| 级别 | 说明 | 行为 | 示例 |
|------|------|------|------|
| L0 | 只读 | 直接执行 | `df -h`, `ps aux`, `cat` |
| L1 | 低风险 | 需确认 | `systemctl restart`, `docker stop` |
| L2 | 高风险 | 强制确认 | `rm -rf`, `iptables -F` |
| L3 | 禁止 | 拒绝执行 | `mkfs`, `dd if=/dev/zero` |

### 安全级别

- **strict** - 所有非只读命令都需确认
- **normal** - 按规则分级（默认）
- **permissive** - 仅 L3 禁止，其余直接执行

### 审计日志

所有执行的命令记录在 `~/.ops-agent/logs/audit.jsonl`，格式：

```json
{"timestamp": "2026-08-01T10:30:00", "command": "df -h", "exit_code": 0, "duration": 0.2}
```

## 输出格式

所有回答遵循固定的精简格式：

```
## 结论
一句话核心发现。

## 关键数据
表格或列表呈现关键指标。

## 建议操作
1-3 条可执行的下一步，附命令。
```

一切正常时只输出一行：`✅ 一切正常，无需操作。`

## 项目结构

```
ops-agent/
├── pyproject.toml
├── config.example.yaml
├── Makefile
├── hook.sh                   # 终端钩子（bash extdebug + DEBUG trap）
├── ops-agent-ask             # 独立客户端脚本
├── ops-agent.spec            # PyInstaller 打包配置
├── install.sh                # 一键安装脚本（分发用）
├── CHECKLIST.md
├── README.md
└── src/ops_agent/
    ├── main.py              # 入口（含 --daemon/--stop/--status/--chat）
    ├── daemon.py            # 后台守护进程（Unix socket 服务端）
    ├── client.py            # Socket 客户端（同步/异步）
    ├── cli/                 # CLI 前端
    │   ├── app.py           # 主循环
    │   ├── renderer.py      # rich 渲染
    │   └── completer.py     # 自动补全
    ├── agent/               # Agent 核心
    │   ├── core.py          # ReAct 循环
    │   ├── planner.py       # 任务规划
    │   └── prompts.py       # 提示词
    ├── llm/                 # LLM 集成
    │   ├── base.py          # 抽象基类
    │   └── openai_compat.py # OpenAI 兼容
    ├── executor/            # 命令执行
    │   └── runner.py        # 异步子进程
    ├── safety/              # 安全守卫
    │   ├── guard.py         # 命令分级
    │   ├── rules.py         # 安全规则
    │   └── audit.py         # 审计日志
    ├── skills/              # Skill 系统
    │   ├── engine.py        # Skill 引擎
    │   ├── loader.py        # YAML 加载
    │   ├── matcher.py       # 触发匹配
    │   ├── builtins/        # 内置 Skill
    │   │   ├── response_format.py
    │   │   ├── safety_guard.py
    │   │   ├── command_router.py
    │   │   └── context_manager.py
    │   └── templates/       # Skill 模板
    │       └── default.yaml
    └── config/              # 配置管理
        └── settings.py
```

## 开发

```bash
# 安装依赖
uv sync

# 运行
uv run ops-agent

# 添加新依赖
uv add <package>

# 代码结构验证
uv run python -c "from ops_agent.main import main; print('OK')"
```

## 打包分发

可以将 ops-agent 打包为独立二进制，分享给其他人使用。**接收方无需安装 Python 或任何依赖**。

### 构建（开发者操作）

```bash
# 构建独立二进制（自动安装 pyinstaller）
make build

# 输出: dist/ops-agent（单个可执行文件，约 21 MB）
# 包含 Python 运行时 + 所有依赖，接收方无需安装 Python
```

### 制作分发包

```bash
# 一键打包为 tar.gz
make dist

# 输出: ops-agent-YYYYMMDD.tar.gz（约 20 MB）
# 包含: ops-agent 二进制 + install.sh + hook.sh + config.example.yaml
```

### 接收方安装

将 `ops-agent-*.tar.gz` 发送给接收方，对方只需：

```bash
# 解压
tar xzf ops-agent-*.tar.gz

# 安装（一键完成）
./install.sh
```

安装脚本自动完成：
- 二进制 → `~/.local/bin/ops-agent`
- 钩子脚本 → `~/.ops-agent/hook.sh`
- 示例配置 → `~/.ops-agent/config.yaml`（仅首次）
- 创建日志目录 `~/.ops-agent/logs/`

### 接收方后续配置

```bash
# 1. 添加 PATH（install.sh 会提示）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 2. 加载钩子
echo 'source ~/.ops-agent/hook.sh' >> ~/.bashrc
source ~/.bashrc

# 3. 配置 API Key
vim ~/.ops-agent/config.yaml
# 填入 api_key 或设置环境变量: export DASHSCOPE_API_KEY=xxx

# 4. 启动
ops-agent --daemon
```

### 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Linux x86_64 |
| Python | **不需要**（已打包在二进制中） |
| 网络 | 需要访问 LLM API（DashScope/DeepSeek 等） |
| 磁盘 | ~100 MB（二进制 + 配置 + 日志） |

### 分发方式对比

| 方式 | 适用场景 | 接收方要求 |
|------|----------|------------|
| **二进制分发包** | 分享给同事/团队 | 仅需 Linux，零依赖 |
| **源码 + uv** | 开发者/需要定制 | Python 3.10+ / uv |
| **pip install** | Python 环境已有 | Python 3.10+ / pip |

### 注意事项

- 二进制仅在构建时的 Linux 架构上运行（Linux x86_64 构建 → Linux x86_64 运行）
- 不支持 macOS/Windows（项目本身依赖 Linux 特性：Unix socket、bash extdebug）
- 如需跨平台，接收方需使用源码安装方式
- API Key 由接收方自行配置，不会包含在分发包中

## 依赖

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) - 包管理
- prompt-toolkit - 交互式 CLI
- rich - 终端渲染
- openai - LLM API（兼容 DashScope/DeepSeek/Ollama）
- pydantic-settings - 配置管理
- pyyaml - Skill YAML 解析
- loguru - 日志