English · 简体中文（本页）

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 控制层：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 负责排障模板、工具目录、工具说明与扩展规范。

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 的存储位置。

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

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

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

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

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

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

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

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

系统实际使用的提示词位于 config/prompt.yaml，主要分为以下几组：

• 支持 Linux 系统
• 执行工具需要安装额外系统级依赖

• Python：建议 3.10 及以上
• 核心 Python 依赖：
  • smolagents
  • litellm
  • openai
  • pyyaml
  • rich
  • pytest
• 可选 playbook RAG 依赖：
  • chromadb
  • sentence-transformers

不同工具会按需依赖不同 Linux 命令，常见包括：

• ip
• ping
• ss
• systemctl
• journalctl
• iptables
• nft
• ufw
• dig
• nc
• tcpdump
• traceroute
• mtr
• ethtool
• bridge
• arping
• conntrack

• 默认 safe_mode=true，执行器会用 AST 做严格的白名单安全检查，并限制高危导入与调用； safe_mode=false 时改为 AST 黑名单匹配，高危调用可能会被模型绕过。
• 工具依赖由统一运行时检查，缺失时可通过 /toolsinstall 查看安装建议。
• 抓包文件默认写入 runtime workspace，进程退出后会被自动清理。
• 工具目录在启动时生成会话级快照，新增或删除工具后必须重启进程以实现加载。

git clone [email protected]:Joeen-AI-Labs/Netiarius.git
cd Netiarius

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

如果你要验证标准安装的依赖层，也可以执行：

pip install .

从源码仓库直接运行时，仍建议优先使用 pip install -e .。

如需安装测试依赖：

pip install -e '.[test]'

如需兼容旧的安装习惯，也可以继续执行：

pip install -r requirements.txt

说明：

• pyproject.toml 是唯一的依赖与版本定义来源
• requirements.txt 只是兼容包装，会转而安装当前项目

Ubuntu / Debian 示例：

sudo apt-get update
sudo apt-get install -y iproute2 iputils-ping netcat-openbsd dnsutils traceroute mtr-tiny ethtool iptables nftables ufw conntrack tcpdump bridge-utils arping

CentOS / RHEL 示例：

sudo yum install -y iproute iputils nc bind-utils traceroute mtr ethtool iptables nftables ufw conntrack-tools tcpdump bridge-utils arping

如果你不确定缺什么，也可以先启动系统后执行 /toolsinstall，再按提示补装。

推荐先复制示例配置，再填写你自己的本地模型参数：

cp config/config.example.yaml config/config.yaml

方式一：直接编辑 config/config.yaml

llm:
  provider: ""
  base_url: ""
  api_key: ""
  model_name: ""

其中：

• provider 可选 openai 或 ollama
• base_url 填写你实际使用的兼容 API 地址或本地模型服务地址
• model_name 填写你实际使用的模型标识

方式二：使用环境变量：

export AI_API_KEY="你的密钥"

方式三：启动后在 CLI 中执行 /model，按向导输入：

1. provider
2. model_name
3. base_url
4. api_key 或 use-env

• 项目版本唯一来源为 pyproject.toml
• config/config.yaml 不维护独立版本号
• 安装产物、CLI 启动日志与后续 Git tag 应统一对齐该版本源

1. provider、base_url、model_name 统一读取自 config/config.yaml
2. 如果通过 /model 配置，这些值会被写回 config/config.yaml，后续运行仍以该文件为准
3. api_key 优先读取 config/config.yaml 中的 llm.api_key
4. 当 llm.api_key 为空时，系统回退到环境变量 AI_API_KEY
5. 当前实现没有 provider、base_url、model_name 的环境变量覆盖层

• 系统默认使用 HF_ENDPOINT=https://hf-mirror.com 作为 Hugging Face 下载镜像
• 这个默认值只会在你没有预先设置 HF_ENDPOINT 时生效
• 如果你所在地区或网络环境需要其它镜像或官方地址，可以在启动前自行设置环境变量

例如：

export HF_ENDPOINT=https://huggingface.co

或：

export HF_ENDPOINT=https://你的镜像地址

系统会优先尊重你预先设置的 HF_ENDPOINT，不会在启动时覆盖。

如果当前环境不需要向量匹配，或者不希望安装嵌入模型，可在 config/config.yaml 中关闭：

playbook_rag:
  enabled: false

source .venv/bin/activate
netiarius

如果你处于源码调试场景，也可以直接运行：

python main.py

source .venv/bin/activate
netiarius

启动后建议先执行：

/help
/model
/model_test
/tools

User > 查看本机 80 端口是否监听
Netiarius > ...

在这个模式下，系统会根据问题判断是直接回答，还是先调用本机工具再回答。

User > /plan
User (plan)> 本机能 ping 通网关，但访问 10.0.0.12:8080 超时，怀疑服务或防火墙异常
Netiarius > 排查计划：
...
开始执行计划(yes) / 继续修改(no)

User (plan)> yes
Netiarius > 诊断结果：
...

Netiarius > 修复计划：
...
开始执行计划(yes) / 继续修改(no)

如果某一步涉及高危动作，系统会自动切到：

User (confirm)> yes

User > /playbook
User > 外部主机无法访问本机 443 端口
User > 1. 使用 ping_probe 检查基础连通性
User > 2. 使用 list_listening_ports 确认服务是否监听
User > 3. 使用 iptables_rules_show 查看入站规则
User > 
User > save

新增工具的标准入口不是改控制层，而是走“工具实现 + 索引更新 + 测试补齐”。

• 只支持 Linux 服务器工具。
• 工具必须统一经过 ToolRuntime。
• 不要在运行时核心按工具名硬编码分支。
• 高危工具必须声明 preflight。
• 复杂工具的轨迹渲染放在工具模块内部，而不是去改运行时核心。
• 新增或删除工具后必须重启进程，工具目录不会热更新。

1. 选择已有模块或新建 tools/*.py
2. 编写 handler
3. 定义 ToolSpec
4. 注册到模块级 TOOL_SPECS
5. 更新 doc/Index_Tools.yaml
6. 更新 doc/Index_Tools.md
7. 补充测试
8. 重启 Netiarius 验证

所有工具都必须返回统一结构：

{
    "success": bool,
    "output": str,
    "data": dict,
    "error": str | None,
    "missing_dependencies": list[str],
    "install_hint": str | None,
}

from tools.common import ToolArgSpec, ToolSpec, tool_result


def demo_tool(target: str) -> dict:
    return tool_result(
        True,
        output=f"已检查 {target}",
        data={"target": target},
    )


TOOL_SPECS = [
    ToolSpec(
        name="demo_tool",
        module="linux_probe",
        summary="演示工具。",
        description="用于说明 Tool 扩展接入方式。",
        risk_level="low",
        requires_confirmation=False,
        linux_commands=[],
        python_packages=[],
        arg_schema=[
            ToolArgSpec(name="target", arg_type="str", required=True, description="检查目标"),
        ],
        handler=demo_tool,
    )
]

高危工具必须同时满足：

• risk_level="high"
• requires_confirmation=True
• 声明 preflight

如果是查询型工具，建议按需补充：

• trace_renderer
• reference_extractor

完整规范请直接阅读 doc/ADD_Tools.md。

欢迎围绕 CLI Agent、plan、playbook、工具扩展和测试补全提交贡献。

1. 提交前先阅读 doc/systeminfo.md 与 doc/ADD_Tools.md
2. 新增能力时优先复用现有模块，不要破坏当前架构边界
3. 变更工具时同步更新 tools/*.py、doc/Index_Tools.yaml、doc/Index_Tools.md 和 tests/
4. 变更 plan 或对话链路时，补齐对应测试
5. 不要提交真实 api_key、抓包敏感数据或本机隐私配置

source .venv/bin/activate
python -m compileall ai_core tools config
pytest -q

GitHub Actions 会在每次 PR 和 tag 推送时自动执行同样的 compileall + pytest 校验，确保公开仓库中的 rc 版本可重复验证。

• 补充更高质量的 Linux 服务器网络工具
• 丰富 knowledge/playbooks/ 模板
• 提升 plan 诊断与修复链路的稳定性
• 完善高危前置澄清、依赖检测和结果复用能力
• 增强 CLI 交互体验与测试覆盖

本项目采用 MIT License，完整文本见根目录 LICENSE 文件。

• 版权所有者：Joeen
• 版权所有年份：2026
• 你可以在保留原始版权声明和许可证文本的前提下，自由使用、复制、修改、合并、发布、分发、再许可和销售本项目。
• 本项目按“现状”提供，不附带任何明示或暗示担保；因使用本项目造成的任何索赔、损失或其他责任，作者和版权持有人不承担责任。

• 邮箱：[email protected]