Netiarius

# Netiarius

[English](README_EN.md) · 简体中文（本页）

Netiarius命名源自网络（Net）与古罗马网斗士（Retiarius）的结合，是一个基于 `Smolagent-CodeAgent` 架构、聚焦 Linux 服务器网络故障排查与修复的 CLI Agent 系统。

![系统概览](doc/images/overview.png)

## 1. 什么是 Netiarius

Netiarius 是一个面向 Linux 服务器网络场景的风格 CLI Agent，拥有丰富的（50+）排障常用工具。旨在帮助用户在进行日常运维时，对 Linux 服务器相关的网络问题（服务、路由、防火墙等）进行定位与修复，把“问答、排查、修复、验证”收敛到一个终端工作流中。

Netiarius 基于 `Smolagent-CodeAgent` 架构开发。模型通过自主编写 Python 代码进行问题处理与工具调用，具有精简上下文、错误自愈与灵活处理的能力，但对模型的编码能力同样具有较高要求，建议使用 **32B以上的 Coder 类** 大模型进行接入使用，以获得更好的体验。

另外，为了保障模型运行 Python 代码的安全性，避免模型在本地执行恶意代码，系统默认会以 safe_mode（白名单限制）的状态运行。这虽然会牺牲一部分模型性能，但会最大保障 Agent 运行时的安全性，请慎重调整（见“系统指令”章节）。

## 2. Netiarius 能做什么

Netiarius 不是通用聊天机器人，而是一个针对 Linux 服务器网络问题设计的 Agent 框架，系统的主要功能有：

- 回答网络原理类问题，并在需要时切换到基于本机事实的工具检查。
- 调用本机工具完成连通性、DNS、HTTP、TLS、路由、策略路由、邻居表、防火墙、服务、端口、日志、抓包等排查动作。
- 在高危操作前自动触发 `confirm` 人机回环确认机制，避免直接执行路由修改、iptables 变更、服务重启、抓包等动作。
- 支持会话级上下文，上下文窗口可通过系统指令进行自定义调整，收敛排障信息实现诊断定位的连续性。
- 通过 `plan` 模式执行“诊断 -> 修复 -> 验证”的受控排障流程，防止 LLM 自由发散，保障排障的严谨性。
- 通过 `playbook` 沉淀可复用的排障模板，让经验从一次会话升级为长期知识资产。

### 主要能力1：`agent`

`agent` 是系统的的常规运行模式，用于满足基础运维与问答的常用操作：

- 系统启动后，默认处于 `agent` 模式
- 在响应用户输入时，优先调用 Tools 进行事实确认，根据事实信息回答用户问题
- 支持日常聊天与知识咨询类对话
- 对于高危类型工具执行自动触发 HITL 人机回环，执行前说明发现，得到用户确认后进行执行
- 通过 /help 指令查询本机系统指令，并进行系统配置（提示词、LLM、上下文窗口等）

这是 Netiarius 最基础的系统能力，能够满足用户大部分基本故障排查场景。

![对话演示](doc/images/dialog-demo.png)

### 主要能力2：`plan`

`plan` 是系统的关键能力。它不是大模型根据用户的模糊需求进行随意发挥排查，而是一个显式、可确认、可回退的计划执行系统：

- 用户输入 `/plan` 进入排障模式，每一次的排障视为一个独立的系统会话（上下文不共享）。
- 系统根据用户描述的故障现象匹配内置 `playbook` 或由模型生成 `playbook`。
- 匹配或生成的 `playbook` 会作为关键提示词发送给大模型，由大模型结合故障现象与 `playbook` 整理为详细的排查计划书。
- 只有当用户输入 `yes` 后，排查计划书才会被冻结为本轮 `execution_plan` 并开始执行。
- 诊断完成后，系统会继续生成修复计划。
- 修复仍然需要 `yes / no` 控制，必要时穿插 `confirm` 高危确认。
- 修复完成后，系统自动执行验证，并在流程结束后退出 `plan`。

此功能让 Netiarius 具备能落地执行的“排障代理”能力，并满足服务器运维中对排查步骤的严谨性要求。

![排障演示 1](doc/images/troubleshooting-demo-1.png)

![排障演示 2](doc/images/troubleshooting-demo-2.png)

![排障演示 3](doc/images/troubleshooting-demo-3.png)

### 主要能力3：`playbook`

`playbook` 是 Netiarius 的知识库系统，用于承载排障经验：

- 内置 `knowledge/playbooks/` 目录，保存了一些常用的排障模板。
- `plan` 模式会优先利用 `playbook` 做匹配或生成诊断计划。
- 支持通过 `/playbook` 交互式创建自定义模板。
- 支持 `/playbook view` 查看全部或指定模板。
- 支持 `/playbook delete <id>` 删除 `source=user` 的自定义模板。
- 支持轻量 `playbook RAG` 做模板描述匹配，但不把 `playbook` 直接当执行脚本，而是让 LLM 结合故障现象生成执行计划。

简单说，`playbook` 负责“积累经验”，`plan` 负责“执行经验”。

![剧本展示](doc/images/playbook-showcase.png)

### 典型使用场景

- 本机防火墙是否阻断了外部地址 xxx.xxx.xxx.xxx 的流量。
- 服务器无法访问域名 example.com ，需要进行定位。
- 客户端地址 xxx.xxx.xxx.xxx 无法访问本机80端口提供的http服务，进行定位。
- 检查服务器到 xxx.xxx.xxx.xxx 的网络连通性是否正常。

## 3. 系统架构

Netiarius 当前按“控制层 / 执行层 / 知识层”组织，整体保留 `CodeAgent` 风格，但把能力收束到 Linux 服务器网络排障。

![系统交互结构](doc/images/interaction-structure.png)

### 架构分层

- 控制层：`ai_core/conversation/`、`ai_core/plan/`、`ai_core/tooling/`
负责命令解析、模式切换、上下文管理、工具目录快照、`plan` 状态机、`playbook` 管理、高危前置澄清与确认。
- 执行层：`ai_core/agent.py`、`ai_core/executor/`
负责构建 `HitlCodeAgent`、适配 `smolagents` 执行器接口，并通过 `LocalExecutor` 在本地受控执行 Agent 生成的 Python 代码。
- 知识层：`knowledge/playbooks/`、`doc/Index_Tools.yaml`
负责排障模板、工具目录、工具说明与扩展规范。

### 运行链路

```text
main.py
  -> 加载 config/config.yaml 与 config/prompt.yaml
  -> 创建 runtime workspace（进程退出自动清理）
  -> 初始化 ConversationManager
      -> ToolCatalogLoader / ToolRegistry
      -> ToolRuntime / DependencyChecker / HighRiskPreflight
      -> PlaybookStore / PlaybookMatcher / PlanExecutor
      -> HitlCodeAgent + LocalExecutorAdapter + LocalExecutor
  -> 进入 CLI 循环
      -> /命令 走控制层
      -> 普通问题走 agent
      -> 排障问题走 plan
      -> 高危动作进入 confirm
```

### 核心模块

- `main.py`
CLI 入口，初始化环境、日志和 runtime `workspace`。
- `ai_core/conversation/manager.py`
整个系统的会话总控，负责模式、命令、上下文、模型配置和主流程调度。
- `ai_core/plan/executor.py`
负责 `playbook` 草案生成、`execution_plan` 冻结、诊断执行、修复计划、修复执行和验证。
- `ai_core/tooling/runtime.py`
统一工具入口，负责参数提取、依赖检查、轨迹记录和高危确认拦截。
- `ai_core/executor/local.py`
通过 AST 安全检查和 `exec()` 在本地执行 Agent 生成代码。
- `knowledge/playbooks/`
内置与自定义 `playbook` 的存储位置。

### 目录结构

```text
Netiarius/
├── ai_core/
│   ├── agent.py
│   ├── conversation/
│   ├── executor/
│   ├── plan/
│   └── tooling/
├── config/
│   ├── config.yaml
│   └── prompt.yaml
├── doc/
│   ├── systeminfo.md
│   ├── ADD_Tools.md
│   ├── Index_Tools.yaml
│   └── Index_Tools.md
├── knowledge/
│   └── playbooks/
├── tools/
│   ├── linux_probe.py
│   ├── linux_route.py
│   ├── linux_l2.py
│   ├── linux_firewall.py
│   ├── linux_service.py
│   └── linux_capture.py
├── tests/
├── pyproject.toml
├── main.py
└── requirements.txt
```

## 4. 系统说明

### 交互模式


| 模式        | 输入提示              | 用途                      |
| --------- | ----------------- | ----------------------- |
| `agent`   | `User >`          | 默认模式，适合问答、低风险检查和普通工具调用  |
| `plan`    | `User (plan)>`    | 显式排障模式，按计划执行诊断、修复、验证    |
| `confirm` | `User (confirm)>` | 高危操作确认模式，只接受 `yes / no` |


Agent 输出前缀为 `Netiarius >`，系统信息直接左对齐显示，无额外前缀。

### 交互规则

- 默认进入 `agent` 模式。
- 输入 `/plan` 后，系统会要求描述故障现象，并自动生成排查计划。
- `plan` 中所有关键推进节点都使用 `yes / no` 控制。
- 高危工具不会直接执行，而是先进入 `confirm`。
- 高危请求如果缺少关键参数，会先走确定性前置澄清，而不是让模型盲猜。
- 每次启动都是独立会话，未实现多会话持久化。
- runtime `workspace` 仅对当前进程有效，进程退出后自动清理。

### `plan` 工作流

1. 输入 `/plan`。
2. 描述故障现象。
3. 系统匹配或生成参考 `playbook`。
4. 系统展示排查计划书，等待 `yes / no`。
5. 用户输入 `yes` 后，计划冻结为本轮 `execution_plan`。
6. 系统逐步执行主流程诊断步骤。
7. 若存在多个低置信候选原因，系统会先暂停，等待是否继续生成修复计划。
8. 生成修复计划后，再次等待 `yes / no`。
9. 执行修复并自动验证。
10. 流程结束后自动退出 `plan`。

### `playbook` 工作流

1. 输入 `/playbook`。
2. 输入模板描述。
3. 逐行输入排查步骤，空行结束。
4. 系统自动提取建议工具。
5. 输入 `save` 写入 `knowledge/playbooks/`，输入 `cancel` 放弃。

### 上下文组成

发送给模型的上下文不是纯聊天记录，而是四段拼装结果：

- 归档摘要
- 工具结果上下文
- 最近对话历史
- 当前用户输入

这意味着工具结果会进入后续轮次，`/show_tool_trace` 只影响前台展示，不影响模型是否能看到工具结果。

### 系统指令


| 指令                                  | 用法                           | 说明                                                            |
| ----------------------------------- | ---------------------------- | ------------------------------------------------------------- |
| `/help`                             | `/help`                      | 显示命令菜单                                                        |
| `/plan`                             | `/plan`                      | 进入排障模式                                                        |
| `/agent`                            | `/agent`                     | 从 `plan` 返回默认模式                                               |
| `/playbook`                         | `/playbook`                  | 进入自定义 `playbook` 创建向导                                         |
| `/playbook view [id]`               | `/playbook view`             | 查看全部或指定 `playbook`                                            |
| `/playbook delete <id>`             | `/playbook delete demo_http` | 删除 `source=user` 的自定义 `playbook`                              |
| `/context window [值]`               | `/context window 12000`      | 查看或修改上下文窗口大小，配置热生效                                            |
| `/safe_mode [true|false]`           | `/safe_mode false`           | 查看或切换执行器安全模式                                                  |
| `/agent_tool_decision [true|false]` | `/agent_tool_decision true`  | 控制是否启用判定优先工具使用的链路                                             |
| `/show_tool_trace [true|false]`     | `/show_tool_trace true`      | 控制前台是否展示工具执行详情                                                |
| `/model`                            | `/model`                     | 进入模型配置向导，依次填写 `provider -> model_name -> base_url -> api_key` |
| `/model_test`                       | `/model_test`                | 测试当前模型连通性                                                     |
| `/systemprompt 内容`                  | `/systemprompt 回答时先给结论`      | 追加本次运行有效的临时系统提示词                                              |
| `/tools`                            | `/tools`                     | 展示当前工具目录快照                                                    |
| `/toolsinstall`                     | `/toolsinstall`              | 检查缺失依赖并给出安装建议                                                 |
| `/toolsinstall pip [包名...]`         | `/toolsinstall pip chromadb` | 安装缺失的 Python 包，未指定时默认安装当前缺失包   

[truncated…]