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

# 启动ui交互界面
witty --tui

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 环境 (如果是控制节点)