witty-ops-agent 0.1.4
Deep Agent with DeepSeek model for natural language processing
Requires Python: >=3.11

# Witty (OpsAgent CLI)

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

## 核心特性

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

## 适用场景

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

## 快速开始

### 1. 安装

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

```bash
# 在 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 依赖，它能提供更快的解析和安装速度。

```bash
# 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 故障诊断模式（默认）

```bash
witty
```

或者使用带参数启动（适合自动化集成）：

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

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

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

#### 3.2 技能生成模式 (Skill Generation)

Witty 支持从文档自动生成运维技能（Skills），支持多种输入格式：

```bash
# 最简单的使用方式（交互式输入技能名称）
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` 配置，用于本地操作。
- **添加新主机**：
  ```yaml
  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.  **构建打包**:
    ```bash
    # 安装构建工具
    pip install build

    # 构建 Wheel 包
    python -m build
    ```

3.  **运行测试**:
    需确保已安装 `ansible` 和 `sshpass` (Linux/Mac)。

## 注意事项

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