OpsAgent:基于运维场景的智能故障定位与分析框架

可用于快速响应线上故障、缩短MTTR并降低人工分析成本。该框架通过自然语言交互实现故障诊断与分析,具备智能多代理架构、根因分析引擎、灵活扩展机制及交互式诊断功能,支持工具生态集成与文档化输出。【此简介由AI生成】

Branch2Tags0

Witty (OpsAgent CLI)

OpsAgent 是一个基于运维场景的智能故障定位与分析框架,通过自然语言交互实现故障的快速诊断、深度分析与文档化输出。Witty 是 OpsAgent 的命令行交互客户端。

核心特性

  • 智能多代理架构 - 基于 DeepAgents 构建数据采集 Agent 和分析 Agent,实现故障信息的自动收集与智能分析
  • 根因分析引擎 - 内置 RAC-Agent(Root Cause Analysis),快速定位故障根本原因
  • 灵活扩展机制 - 通过自定义 Skills 轻松扩展新的故障定位场景,适配不同运维需求
  • 交互式诊断 - 友好的命令行交互界面 (CLI),实时展示故障定位过程与详细分析报告
  • 开箱即用 - 内置配置管理与初始化功能,自动化环境准备
  • 工具生态集成 - 支持通过 MCP(Model Context Protocol)协议扩展外部工具能力

适用场景

  • 快速响应线上故障,缩短 MTTR(平均修复时间)
  • 自动化故障诊断流程,降低人工分析成本
  • 沉淀故障分析经验,输出标准化诊断报告

快速开始

1. 安装

方式一:从源码安装 (推荐开发/测试)

# 在 macOS 上使用 Homebrew
brew install ansible sshpass

# 在 Debian/Ubuntu 上使用 apt
sudo apt-get update && sudo apt-get install -y ansible sshpass

# 在 CentOS/RHEL 上使用 yum
sudo yum install -y ansible sshpass

2. 安装项目依赖

我们推荐使用 uv 来管理 Python 依赖,它能提供更快的解析和安装速度。

# 1. 拉取项目
git clone --recursive git@gitcode.com:leon-wang2021/witty-agent.git
cd witty-agent
git submodule init              # 初始化子模块(本项目依赖第三方工具)
git submodule update            # 如已拉取,可用此命令更新子模块代码

# 2. 使用 uv 创建并激活虚拟环境(推荐)
uv venv
source .venv/bin/activate

# 3. 安装 witty
uv pip install -e .

3. 启动程序

3.1 故障诊断模式(默认)

witty

或者使用带参数启动(适合自动化集成):

# 直接传入问题
witty -q "My server is CPU overloaded"

# 跳过安全确认
witty -q "Check disk usage" --no-security-check

3.2 技能生成模式 (Skill Generation)

Witty 支持从文档自动生成运维技能(Skills),支持多种输入格式:

# 最简单的使用方式(交互式输入技能名称)
witty skill-gen --input /path/to/document.pdf

# 从单个文件生成技能(PDF/TXT/Markdown)
witty skill-gen --input /path/to/document.pdf --skill-name "my_skill"

# 从目录批量生成技能(自动处理目录下所有pdf文档)
witty skill-gen --input /path/to/documents/ --output ~/.witty/skills/custom/

# 指定并发级别(默认 3)
witty skill-gen --input /path/to/documents/ --concurrency 5

参数说明:

  • skill-gen: 技能生成子命令
  • --input: 输入文件或目录路径(支持 PDF、TXT、Markdown 文件,或包含这些文件的目录)
  • --output: 输出目录路径(默认:CUSTOM_SKILL_PATHS 环境变量指定的路径)
  • --concurrency: 批量生成时的并发级别(默认:3)
  • --skill-name: 单文件生成时指定技能名称(可选,未提供时会自动生成或交互式询问)

4. 初始化与配置

Witty 在首次运行时,会自动在用户主目录下创建工作区 ~/.witty,并释放默认配置文件。

工作区结构 (~/.witty/):

  • config.yaml: 核心配置文件(模型参数、系统设置)
  • inventory.yaml: 主机清单文件(定义被管节点)
  • skills/: 内置技能库
  • template/: 内置skill模板
  • .env: 环境变量配置 (API Keys)

你可以在 ~/.witty/.env 中配置你的 DEEPSEEK_API_KEY,或者在启动时根据交互提示输入。

主机清单配置 (inventory.yaml)

~/.witty/inventory.yaml 文件用于定义和管理 Agent 需要连接的目标服务器。

  • 默认配置:默认包含 localhost 配置,用于本地操作。
  • 添加新主机:
    all:
      children:
        default:
          hosts:
            web-server-01:
              ansible_host: 192.168.1.100
              ansible_user: root
              # 更多 Ansible 连接参数...
    

开发与贡献

项目采用了标准 Python src 布局,请遵循以下开发规范:

  1. 代码位置: 所有源代码位于 src/witty/ 目录下。

    • src/witty/cli: 命令行入口逻辑
    • src/witty/core: 核心 Agent 业务逻辑
    • src/witty/resources: 静态资源与配置模板
  2. 构建打包:

    # 安装构建工具
    pip install build
    
    # 构建 Wheel 包
    python -m build
    
  3. 运行测试: 需确保已安装 ansible 和 sshpass (Linux/Mac)。

注意事项

  • 需要有效的 DeepSeek API Key
  • 确保网络连接正常以访问 DeepSeek API
  • 确保系统已安装 Ansible 环境 (如果是控制节点)

Introduction

可用于快速响应线上故障、缩短MTTR并降低人工分析成本。该框架通过自然语言交互实现故障诊断与分析,具备智能多代理架构、根因分析引擎、灵活扩展机制及交互式诊断功能,支持工具生态集成与文档化输出。【此简介由AI生成】

Customize your domain