Crux - GPU 服务器运维 Agent

一个能同时看懂沐曦（mx-smi）和通用 GPU（nvidia-smi/all-smi）运行状况的 Agent，能聊天诊断，能终端看板，能交互式会话，还能为 Web 面板留好接口–只读、小巧，但骨架完整。

安全原则：目前版本只读、只分析、只建议，不执行任何会改变服务器状态的操作。

一、快速开始

1. 环境要求

Python 3.10+
（真实沐曦服务器）mx-smi 已安装并在 PATH
（可选 LLM）Ollama / Agnes AI / 任何 OpenAI 兼容接口

2. 安装

cd cruxmvp pip install -e .

安装后 crux 命令全局可用。依赖全部为纯 Python 包，无系统级编译。 fastapi/uvicorn 仅 crux web 需要，缺失时自动降级为 stdlib HTTP 服务。

3. 第一次运行

# 无 GPU 环境演示（仿真数据，验证流程）
CRUX_COLLECT__MOCK=true CRUX_LLM__BACKEND=none crux status

# 真实沐曦服务器（自动探测 mx-smi，无 LLM 走规则降级）
crux status

# 交互式终端会话（类似 Claude Code 的 REPL）
crux session

二、CLI 命令

命令	作用
`crux status`	一次性健康报告（GPU/MACA/事件）
`crux chat "问题"`	对话式诊断（FP8、MACA 污染、性能瓶颈）
`crux session`	交互式终端会话（支持 `/set-key` 设置 API Key）
`crux dashboard`	终端实时监控面板（`--once` 渲染一次）
`crux web --port 8080`	启动 Web REST API
`crux collect --debug`	手动采集 + 打印 mx-smi 原始输出（真机适配用）
`crux rules`	列出所有规则
`crux tools`	列出所有工具

也可以用 python agent.py <命令> 代替 crux <命令>。

交互式会话（`crux session`）

启动后进入 REPL，支持以下命令：

输入	作用
`/set-key <KEY>`	设置 Agnes API Key，自动切换到 Agnes 云端 LLM
`/status`	查看当前服务器 GPU/MACA/事件快照
`/tools`	列出所有可用工具
`/rules`	列出所有规则
`/reset`	重置会话上下文
`/help`	显示帮助
`/exit`	退出
直接输入问题	进入诊断，回答后附带 GPU 核心参数表格

诊断示例

$ crux chat "模型加载失败 /models/DeepSeek-FP8"

[现象] 模型加载失败
[根因分析] 模型路径含 FP8 量化标识，沐曦 C500 不支持 FP8
[置信度] 高
[建议] 更换为 FP16/BF16/INT8 版本模型

三、部署到真实沐曦 GPU 服务器

1. 配置 LLM（推荐，但不强制）

方式一：交互式会话内设置

crux session
crux01> /set-key your-agnes-api-key

方式二：环境变量预设

export CRUX_LLM__BACKEND=agnes
export CRUX_LLM__AGNES__API_KEY=your-key
crux session

方式三：配置文件

配置 config.local.yaml（不提交，覆盖 config.yaml）：

llm:
  backend: agnes           # ollama | openai | agnes | none
  agnes:
    base_url: https://apihub.agnes-ai.com/v1
    api_key: your-key
    model: agnes-2.0-flash

无 LLM 也能用：backend=none 时，crux chat 自动走「规则降级」路径，仍能识别 FP8 / MACA 污染 / 性能瓶颈并给出结构化诊断。这是「真实服务器可用」的关键保障。

2. 适配 mx-smi 输出格式

mx-smi 输出格式随版本变化。部署后必须执行一次：

crux collect --debug

查看打印的 mx-smi 原始输出，确认字段是否正确解析。

解析器已内置多策略容错：

KV 提取：按字段别名表（_FIELD_ALIASES）匹配 Key : Value 行
SGPU 配额修正：SGPU 切片环境下用 mx-smi sgpu --show-memory 获取真实显存配额
列式表格兜底：nvidia-smi 风格表格全局正则

支持的 mx-smi 2.2.x KV 字段（真机验证）：

vis_vram total/used（显存，KB 单位）
GPU : N %（利用率）
hotspot(sensor1) : N C（温度）
GPU#N MXC500（设备名从设备行提取）
**若 crux status 的 GPU 字段显示 -**：说明某字段标签未匹配。
打开 providers/mxsmi.py，把真实输出中的字段标签加入 _FIELD_ALIASES 对应列表。
无需改动其它代码。单元测试：python tests/test_mxsmi_parser.py

3. 自动探测的 provider

启动时按 config.yaml -> providers.prefer 顺序探测：

mx-smi（沐曦官方，优先）
all-smi（跨厂商通用）
nvidia-smi（兼容路径）

同一台机器多 provider 同时可用时，以 mx-smi 为主，其它补充缺失字段。

无 GPU 环境行为：provider 可用但采集为空时（如容器内 sysfs 未挂载），返回空列表并明确告警，不回退仿真数据。只有 collect.mock=true 时才返回仿真数据。

4. 启动 Web API

crux web --port 8080
# 默认绑定 127.0.0.1，如需对外暴露：
crux web --host 0.0.0.0 --port 8080

端点：

GET /api/status - GPU/MACA/事件快照
GET /api/metrics?device_id=0&metric=util_pct&minutes=60
GET /api/events?limit=20
GET /api/chat?q=训练为什么慢
GET /api/health

四、架构

CLI / Dashboard / Session  (agent.py / crux_cli.py / dashboard / web_api)
        │
Core Agent Engine  (engine/: tool, tool_registry, workspace, agent_loop, context)
        │
Tool Layer  (tools/: gpu_tools, system_tools, metax_tools  +  registry.py)
        │
Perception  (providers/: base, detector, mxsmi, allsmi, nvidiasmi, mock, cmd)
        │
Persistence  (collector/: collector + storage SQLite)
Rules  (rules/: engine + rules.yaml)   Knowledge  (core/rag.py + knowledge/*.md)

沐曦专属能力

工具	作用
`check_maca_env`	检测 torch/vllm/triton 是否带 +metax/+maca，识别公版库污染
`check_model_quantization`	检测模型路径是否含 FP8（C500 不支持）
SGPU 配额检测	SGPU 切片环境下显示真实显存配额（非物理全量）
规则 R10-R13	FP8 告警、MACA 污染告警、库缺失告警

降级策略（保证真实服务器可用）

组件	缺失时行为
mx-smi / nvidia-smi / all-smi	返回空列表 + 明确告警（不回退仿真数据）
mx-smi 可用但 GPU 不可访问	告警提示检查 sysfs 挂载/容器配置
LLM (Ollama/Agnes)	`crux chat` 走规则降级路径，仍输出结构化诊断
fastapi / uvicorn	`crux web` 降级为 stdlib HTTP 服务
pydantic	数据模型降级为 dataclass
rich	dashboard 降级为纯文本清屏刷新

五、配置

config.yaml 是默认配置。三种覆盖方式（优先级递增）：

config.yaml（默认）
config.local.yaml（部署覆盖，建议加入 .gitignore）
环境变量 CRUX_<段>__<键>（如 CRUX_LLM__BACKEND=none、CRUX_COLLECT__MOCK=true）

LLM 后端

后端	说明	配置段
`ollama`	本地 Ollama 服务	`llm.ollama.base_url` / `model`
`openai`	OpenAI 兼容接口（如 vLLM）	`llm.openai.base_url` / `api_key` / `model`
`agnes`	Agnes AI 云端 API（免费 RPM≤20）	`llm.agnes.api_key` / `model`
`none`	不使用 LLM，走规则降级	-

六、目录结构

cruxmvp/
├── agent.py              # CLI 入口
├── crux_cli.py            # crux 全局命令入口 shim
├── pyproject.toml         # 打包配置（pip install -e .）
├── config.yaml            # 默认配置
├── requirements.txt       # 依赖清单
├── _compat.py             # 配置访问兼容层（破循环导入）
├── engine/                # 核心 Agent 引擎（tool/registry/workspace/loop/context）
├── tools/                 # 只读工具集（gpu/system/metax + registry）
├── providers/             # 感知层（mxsmi/allsmi/nvidiasmi/detector/mock/cmd）
├── collector/             # 采集调度 + SQLite 存储
├── workspaces/            # router/monitor/diagnose
├── rules/                 # 规则引擎 + rules.yaml
├── dashboard/             # 终端面板 + Web API
├── core/                  # config/llm/summarizer/rag/session
├── knowledge/             # 沐曦知识库
└── tests/                 # 单元测试（mxsmi解析/Storage/Router）

七、验证状态

crux status 在沐曦机器正确显示 GPU/MACA 状态（真机验证：MXC500, SGPU 32GB 配额）
crux status 在 nvidia-smi 机器显示通用 GPU 状态
crux chat 识别 FP8 和 MACA 库污染
crux chat 结合利用率/CPU/IO 做性能分析
crux dashboard 实时刷新核心参数（含温度/状态标签）
crux session 交互式终端会话（支持 /set-key 设置 Agnes API Key）
crux web 返回 /api/status JSON
无 GPU 环境明确告警（非仿真数据）
SGPU 切片环境显示真实显存配额
整个系统只读，不执行写操作
单元测试 21 项全部通过（mxsmi 解析器 / Storage / Router）