dea

Debug Anything

观察任何正在运行的进程。无需断点、重启或插桩。

一个 MCP 服务和命令行工具，让任何编码 Agent——Claude Code、Codex、Cursor、Gemini CLI——都能洞察正在运行的软件：系统调用、CPU 火焰图、线程堆栈、套接字和文件描述符、数据包、堆保留对象、容器状态。经过实战检验的本地工具（strace、py-spy、perf、lsof、tcpdump、gdb/lldb、Node 的检查器）负责观察；Debug Anything 则将它们的输出转化为结构化证据，供 Agent 推理和人类审查。

快速开始 · Debug Anything 的工作原理 · 可观察的内容 · 演示 · 工作流 · Python / LangChain / CrewAI · 安全性 · 常见问题 · 路线图 · 社区

npx debuganything why <pid>       # or: why api-container --symptom leak

只需一条命令，即可针对任何 pid、容器或 pod 执行：附加 → 根据症状选择合适的工具（slow / leak / hang / crash / triage）→ 按优先级排序的发现，每项都引用证据 ID → 分离。若要将它连接到 Agent：npx debuganything setup。不想安装？在浏览器中粘贴工具输出。

网站：https://debuganything.dev · 社区：Discord · 讨论区 · 请务必只从此仓库、debuganything npm/PyPI 软件包或该网站下载 Debug Anything。

Debug Anything 的定位

基于 MCP 的单步调试器已经存在，而且表现不错：debugmcp/mcp-debugger（7 种语言）、microsoft/DebugMCP（VS Code）、jdwp-mcp（Java）、jkolo/debug-mcp（.NET）、pprof-mcp-agent（Go）。它们需要调试适配器、调试端口，或经过插桩/重启的目标；并且假设你已经知道断点应该设在哪里。

Debug Anything 是更前置的一层：无需任何插桩，即可对任意 pid、容器或 pod 进行黑盒观察，并将结果转化为证据。

知道断点该设在哪里时，用 mcp-debugger；不知道时，用 Debug Anything。

两者可以互相补充。当 Debug Anything 将问题定位到某个函数或线程时，其 suggested_next 会提供后续步骤：“在 file:function 处附加单步调试器（例如 mcp-debugger）”；对于原生符号，还会建议“使用静态分析工具反编译 libfoo.so 中的 parse_frame”。更多场景：docs/examples.md。

为什么要做这个项目

软件只编写一次，却会一直运行，而大多数工程痛点都出在运行阶段。Agent 刚刚在编写代码方面取得了长足进步，但对运行阶段仍一无所知——Agent 可以读完代码的每一行，却仍无法告诉你眼前的进程为什么占用了 4 GB 内存。可观测性厂商通过仪表盘解决了人类的这个问题，却没人为 Agent 解决这个问题。

Debug Anything 是软件 Agent 的感知层。计划如下：

1. 本地 — 一个 MCP、一台笔记本电脑、一个进程。以证据为依据，不靠猜测。（本次发布）
2. 任意位置 — 容器、Pod、通过 SSH 访问的远程主机，以及集群。使用相同的工具和契约。
3. 始终在线 — 监控生产环境的 Agent，在凌晨 3 点发现回归问题，接入并诊断，然后附上火焰图创建 PR，只有在有证据时才通知人工。
4. 标准 — 证据契约（发现必须引用证据）成为任何工具向任何 Agent 报告信息的通用方式，让人类只需点击一次就能审查 Agent 的结论。

每个接口的设计都确保第 1 步编写的代码到第 4 步仍然可用：目标是抽象的（今天支持 pid，现在支持 container 和 pod，接下来支持 host），适配器可插拔，并且每个结果都使用相同的证据架构。不作任何本地主机假设。

快速开始

0. 一行命令

npx debuganything why <pid|container|pod>     # symptom flags: --symptom slow|leak|hang|crash

why 是整个产品浓缩成的一条命令：它会运行就绪检查、接入目标、根据症状选择合适的观测工具组合，并输出按优先级排序的发现及其佐证证据 ID。下面介绍的所有功能，都是将同一套引擎接入你的 Agent。

1. 设置你的 Agent

npx debuganything setup

它会检测 Claude Code、Codex、Cursor 和 Gemini CLI，显示将要添加的确切配置项，备份配置文件、写入配置，并在 Agent 支持技能时安装 debug-anything 技能。然后重启你的 Agent。

一键安装：

Claude Code 插件：/plugin marketplace add shreyassaw5394/debuganything，然后运行 /plugin install debuganything@debuganything · Gemini CLI：gemini extensions install https://github.com/shreyassaw5394/debuganything · 技能：npx skills add shreyassaw5394/debuganything

2. 向你的 Agent 提问

我的 API 运行几分钟后就会变慢——接入它并用证据告诉我原因。

有东西占用了端口 8080。是什么？

这个 Python 工作进程处理大约 20 个请求后就会挂起。查明它在等待什么。

Agent 会调用 readiness、attach，然后调用合适的工具，并给出引用证据 ID 的发现结果；如果无法观测到某些情况，也会告诉你原因。

3. 没有 Agent？运行一条命令

npx -y debuganything@latest why 12345 --symptom leak     # or: slow | hang | crash | triage
debuganything why my-container --symptom crash
debuganything why -- node server.js                             # spawn it under observation

why 会接入目标、根据症状运行合适的工具、输出每项结果，并 最后给出按优先级排序的摘要和报告路径。若 readiness 指出某些工具 无法运行，它会跳过这些工具，而不是报错退出。

4. 或逐步操作

npx -y debuganything@latest readiness
debuganything ps --filter node
S=$(debuganything attach 12345 --json | jq -r .session_id)
debuganything profile --session $S --duration 10
debuganything sockets --session $S
debuganything report  --session $S --md report.md
debuganything detach  --session $S
debuganything port 8080                      # who holds a port — no session needed

每条命令都支持 --json，并会输出准确的 ToolResult。请参阅 docs/cli.md。

5. 为整个团队设置代码库

cd my-project && debuganything init     # .mcp.json + .cursor/mcp.json + a rule in AGENTS.md/CLAUDE.md — commit them

现在，每位队友的 Claude Code 和 Cursor 都能从代码库中使用 Debug Anything，并且规则会告诉 Agent 何时使用它。按天了解采用流程：docs/workflows.md。

6. 安装为 Agent 技能

debug-anything 技能（调查指令、证据规则、征求同意的礼仪）会由 setup 为 Claude Code、Codex 和 Gemini CLI 安装，也可以通过 skills.sh 获取：

第二个技能 inspect-product 用于审查整个产品，而不是追查某个 Bug：Agent 会以全新用户的身份浏览正在运行的应用，使用这些工具观察其底层运行时，并返回经过排序的发现，每项发现都附带复现方法和证据。请让它“审查产品，并告诉我发布前要修复什么”。两个技能都可通过 npx debuganything setup 安装。

npx skills add shreyassaw5394/debuganything

7. 更新

debuganything update                        # or: npx debuganything@latest setup

Debug Anything 的工作原理

agent ──MCP──▶ Debug Anything server ──▶ dispatcher ──▶ adapter (strace | py-spy | perf | lsof | tcpdump | gdb/lldb | inspector | docker)
                                 │                │  build command → run with caps → write raw artifact → parse → aggregate
                                 ▼                ▼
                           ToolResult { findings[] ──cite──▶ evidence[] ──point──▶ artifacts[] }  + limitations + suggested_next

• 会话。 attach 会将目标（pid、容器、Pod，或在捕获模式下启动的命令）解析到 ~/.debuganything/sessions/<id>/。每个工具结果都会保存为一次运行（profile_cpu#2），因此 diff_runs 可以比较前后状态，report 可以汇总整个调查。
• 证据约定。 没有 evidence_ids 的 Finding 会被架构拒绝。允许使用 confidence: "inferred"，但必须明确说明。Agent 只能声称证据所支持的内容。完整架构：docs/mcp-contracts.md。
• 适配器。 每个适配器都会声明支持的平台、所需二进制文件以及提供的工具；readiness 会计算这台机器上哪些功能可用。解析器是纯函数，并使用实际捕获的输出进行测试。新增一个适配器约需 80 行：CONTRIBUTING.md。
• 提示词。 dea_slow、dea_leak、dea_hang、dea_crash、dea_port_busy 是引导式调查：它们规定工具的使用顺序、需要关注的内容，以及绝不在没有证据 ID 的情况下陈述原因的规则。

可以观察的内容

0.4 版新增：Java 线程转储（jstack，实时获取或导入）、Go goroutine 转储、粘贴内容即可使用的浏览器分析器、可分享的 HTML 报告（debuganything report --html）、跨会话基线差异对比（debuganything diff --session now '<baseline>:<run>' <run>），以及作为 GitHub Action 的 CI 挂起问题取证。

目标	Debug Anything 返回的内容	要求
任意进程：套接字（inspect_sockets）	监听端口、按远程端分组的连接、CLOSE_WAIT / TIME_WAIT / SYN_SENT 堆积、文件描述符数量与 ulimit 的对比	lsof — Linux、macOS；检查自己的进程无需 root
任意进程：文件（inspect_files）	按类型统计文件描述符、统计一段时间内文件描述符的增长、最大的打开文件、占用磁盘空间但已删除仍保持打开状态的文件	lsof — Linux、macOS（已删除但仍保持打开：仅限 Linux）
任意进程：内存（snapshot_memory）	RSS/VSZ 序列、/proc 状态（匿名内存 / 文件内存 / 交换空间 / 线程）	ps — Linux、macOS
Node.js：堆（snapshot_memory）	V8 堆快照、按类型和构造函数统计字节数、按保留大小排列的主要保留者及其保留路径（Context.retained、Map.table…）	Node 的 inspector（如有需要，通过 SIGUSR1 启用）— Linux、macOS
Node.js：JS 堆栈（dump_stacks）	主线程 JS 调用帧、事件循环处于空闲还是阻塞状态	Node 的 inspector — Linux、macOS
Python：CPU（profile_cpu）	按自身 / 总耗时排列的主要帧、最繁忙的堆栈、flamegraph.svg	py-spy — Linux（ptrace_scope=0 或 root）、macOS（sudo）
Python：线程（dump_stacks）	每个线程的堆栈；根据源代码行（with lock_b:）将阻塞线程分类为锁 / join / 休眠 / I/O；死锁检测	py-spy — Linux、macOS（sudo）
macOS：文件和网络系统调用（trace_syscalls）	通过 fs_usage 获取每次调用的耗时、阻塞调用、errno（ENOENT、ECONNREFUSED…）；需要 root，因此 Debug Anything 会打印 sudo 命令，然后你运行 debuganything import fs_usage <file>	fs_usage — macOS，预装
自行捕获的任何内容（debuganything import）	strace、fs_usage、perf script、py-spy、sample、gdb/lldb、lsof、tcpdump 文本 → 与实时运行相同的证据和发现。回答“需要 root 吗”这个问题	—
Linux：系统调用（trace_syscalls）	按总耗时和调用次数排列的主要系统调用、带路径 / 地址的最慢调用、错误计数（ENOENT、EAGAIN、ECONNREFUSED…）、阻塞等待占用的时间比例	strace — Linux；ptrace_scope=0 或 root
原生 / Node / Go / Java：CPU（profile_cpu）	perf 采样 → 折叠堆栈 → flamegraph.svg（无需 Perl），区分空闲与工作状态	perf — Linux（perf_event_paranoid ≤ 1 或 root）；Node 需要 --perf-basic-prof 才能显示 JIT 名称
原生 / Node：macOS 上的 CPU（profile_cpu）	sample 调用图 → 折叠堆栈 → 火焰图	sample — macOS，预装
原生 / Node / Go / Java：线程（dump_stacks）	所有线程的回溯、处于互斥锁等待 / 条件等待 / 阻塞 I/O 中的线程、死锁启发式检测	gdb — Linux；lldb — macOS
网络（capture_traffic，需征得同意）	按远程端统计数据包 / 字节数、RST、未响应的 SYN、可能的重传、DNS 查询、.pcap 文件；根据目标自身的端口派生过滤器，绝不使用无界过滤器	tcpdump — Linux、macOS；root / CAP_NET_RAW / access_bpf
Docker 容器（container_info）	状态、OOMKilled、退出码、重启次数、内存 / CPU 限制与使用情况、cgroup 限流和 OOM 事件、已发布端口、日志尾部的错误行；为其他每个工具提供容器 → 主机 pid 映射	docker — Linux（可见主机 pid）、macOS（仅限 container_info）
Kubernetes pod（attach ns/pod）	当 kubelet 在此主机上运行时（kind、minikube、k3s），将 pod 的容器解析为本地 pid	kubectl — 实验性
正在使用的端口（debuganything port N）	占用该端口的 pid、命令行和用户，或残留的 TIME_WAIT/CLOSE_WAIT	lsof
前后对比（diff_runs）	同一工具的两次运行之间增长、缩小、新出现或消失的内容	—
Windows	尚不支持 — readiness 会说明	计划支持：ETW、procdump
坦诚说明：以上所有内容均在 Linux（Debian 12 容器，以 root 身份运行）和 macOS 15（以当前用户进程运行，不使用 sudo）上，针对示例应用进行了实际测试。bpftrace 脚本已准备好，但尚未接入工具。各操作系统的安装命令见：docs/providers.md。

示例

真实场景——CLOSE_WAIT 堆积和 EMFILE、磁盘已满但 du 显示不一致、Postgres 连接池耗尽、Celery 死锁、Node 事件循环阻塞、Pod 被 OOMKilled、每次请求都进行 DNS 查询、崩溃后出现 EADDRINUSE、无法读懂的原生代码热点——每个场景都包含会话、证据和修复方法：docs/real-world.md。

docs/examples.md 中提供了十个可直接复制粘贴的场景——慢 API、内存泄漏、挂起、端口占用、容器崩溃、在监控下启动进程、验证修复、CI 回归门禁、经同意后捕获数据包、Python Agent。

演示

可通过 examples/ 复现。docs/showcases.md 中提供了完整记录；docs/example-report-leaky-node.md 中则有一份由 Debug Anything 自行编写的完整报告。

leaky-node——HTTP 服务会将每个请求体保留在模块级数组中，此外还有一个 /slow 路由，会在循环中执行 readFileSync，并设置一个 800 ms 的计时器。 执行 snapshot_memory ×2 + diff_runs：RSS 从 85 增至 172 MB（+102 %），堆从 37 增至 97 MB；占用内存最多的保留对象是一个 Array，其保留大小从 17 增至 47 MB。执行 trace_syscalls（8 s）：出现 5 600 次 openat/statx 查找和 3 314 次 read() 调用——属于“循环中的同步 I/O”；epoll_pwait 每次休眠约 800 ms。

deadlock-py——多线程服务在第 20 个请求之后以相反顺序获取两把锁。 执行 dump_stacks：worker-ab-20 阻塞在 app.py:26 [with lock_b:]，worker-ba-20 阻塞在 app.py:33 [with lock_a:]，八个请求线程都在等待这两个线程，且没有线程正在运行 →“很可能发生了死锁”，并可将控制权交给位于 worker_ab 的单步调试器。

busy-port——一个进程占用了 :8080，脚本因此报错 EADDRINUSE。 执行 debuganything port 8080：port 8080 is held by pid 47508 (node, user shreyassawant) in LISTEN — command: node server.js. Debug Anything will not kill it; decide yourself.

Agent 无需提示即可使用

安装后，Agent 会被告知主动使用 Debug Anything：当它们运行的命令挂起、测试超时、输出中出现 EADDRINUSE / ECONNREFUSED / EMFILE / exit 137 / OOM / segfault、它们启动的服务没有响应，或你提到慢、挂起、泄漏或崩溃时，都会使用它。对于 Claude Code，setup 还会安装一个轻量级钩子，用于检测命令输出中的这些信号，并提示和引导模型使用合适的 Debug Anything 工具。只读观察无需许可；capture_traffic 始终需要许可。详情和关闭方法（--no-hooks）见：docs/proactive.md。

Python、LangChain、LlamaIndex、CrewAI

pip install debuganything                 # plain client (no deps; uses npx under the hood)
pip install 'debuganything[langchain]'    # debuganything.langchain.debuganything_tools()
pip install 'debuganything[llamaindex]'   # debuganything.llamaindex.debuganything_tools()
pip install 'debuganything[crewai]'       # debuganything.crewai.debuganything_tools()

from debuganything import DebugAnything
debuganything = DebugAnything()
s = da.attach(12345)
print(da.findings(da.profile_cpu(s, duration_s=10)))
da.detach(s)

每个适配器都提供相同的 14 个工具，并使用相同的 ToolResult。原生支持 MCP 的框架可以跳过此软件包，直接运行 npx -y debuganything serve。 详情见：python/README.md。

为什么不直接让 Agent 调试？

因为目前它做不到。Agent 无法附加到进程；它们常常弄不清 strace/perf/lsof 的语法和标志；10 s 的 strace 会生成 1.5 MB 文本，撑爆上下文窗口；而且无法测量时，它们就会自信地猜测。Debug Anything 为它们提供了观察能力（合适的工具、合适的标志，并设有严格上限）和证据（摘要会指向原始材料，结论必须引用这些材料）。你得到的是可审计的诊断，而不是听起来可信的说法。

安全性

• 只读。 v0 工具只观察，不会终止进程、设置断点，也不会使用会修改行为的探针。已说明的例外：Node 目标可能会收到 SIGUSR1，以启用检查器。
• 征得同意。 capture_traffic 需要 consent: true；技能会告知 Agent 先征求你的同意。
• 严格限制。 每个工具最多运行 60 s（捕获任务为 30 s），磁盘上的原始输出最多 50 MB，返回给 Agent 的内容最多 16 KB（摘要 + 指针；引用的证据不会被丢弃）。每个子进程都会先收到 SIGTERM，随后收到 SIGKILL。
• 绝不使用 sudo。 如果某个工具需要 root 权限，你会收到 ok: false 和可由你自行运行的准确命令。readiness 会提前报告 ptrace_scope、perf_event_paranoid、SIP 和 sudo -n 状态。
• 范围受限。 适配器只会访问已附加的 pid 树或容器。捕获内容会按目标端口筛选，并拒绝不受限的运行。
• 机密信息。 返回给 Agent 的所有内容都会对 Bearer 令牌、AWS 密钥、JWT、password=、API 密钥、私钥和 user:pass@ URL 进行脱敏。磁盘上的原始产物不会脱敏——请将 ~/.debuganything/sessions/ 视为敏感目录。
• 不使用云服务，不收集遥测数据。 Debug Anything 不会自行发起任何网络请求。所有内容都保留在你的设备上。

详情：docs/safety.md · DISCLAIMER.md · SECURITY.md

常见问题

哪些 Agent 可以使用？ 任何支持通过 stdio 使用 MCP 的 Agent 都可以。setup 支持 Claude Code、Codex、Cursor 和 Gemini CLI；对于其他 Agent，请将 {"command":"npx","args":["-y","debuganything@latest","serve"]} 添加到 MCP 配置中（docs/installation.md）。

我需要安装 strace / perf / py-spy 吗？ 只需安装你想用的工具。readiness 会列出可用工具并提供安装提示。在 Linux 和 macOS 上，lsof、ps 和 Node 的检查器开箱即用。

需要 root 权限吗？ 在 macOS 上检查你自己的进程时（lsof、sample、lldb、检查器），或在 ptrace_scope=0 的 Linux 上，不需要。macOS 上的 py-spy 和 fs_usage，以及所有系统上的 tcpdump 则需要 root 权限；Debug Anything 会打印准确的 sudo 命令，由你运行，然后使用相同的解析器通过 debuganything import <tool> <file> 分析输出。

在 macOS 上它看不到什么？ macOS 没有 strace 或 perf。fs_usage（通过导入）可以捕获文件和网络调用；sample、lldb、lsof 和 Node 检查器可以覆盖其余内容。如需完整的系统调用和内核时间信息，请在 Linux 容器中运行目标（docker/linux-lab）。

Debug Anything 会上传任何内容吗？ 不会。它不会发起网络请求、收集遥测数据或检查更新；只有显式运行 debuganything update 时例外。

它能调试 Docker 容器吗？ 在 Linux 上可以——按容器名称附加，所有工具都会通过宿主机 pid 工作。在 macOS 上，Docker VM 会隐藏 pid，因此从宿主机只能使用 container_info；请改为在容器内运行 Debug Anything（docker/linux-lab 提供了包含所有提供程序的镜像）。

这与逐步调试器有什么不同？ Debug Anything 绝不会让程序停在某一行。它会对运行中的进程进行采样、跟踪和快照，并告诉你应该在哪里查看。然后交由 mcp-debugger 或 IDE，让你查看程序的内部。

产物存放在哪里？ ~/.debuganything/sessions/<id>/（可通过 DEA_HOME 覆盖）。使用 debuganything sessions list / debuganything sessions prune。

路线图

bpftrace 预置脚本 · 通过临时调试容器支持 Kubernetes pod · Windows（ETW、procdump）· Java（async-profiler、jcmd Thread.print）· Go（pprof、delve goroutine 转储）· Rust/C++ DWARF 栈展开 · Linux 上优先使用 eBPF 跟踪 · Python tracemalloc/memray · 通过检查器 Profiler 获取 Node CPU 信息 · 锁所有者关系图 · 通过 SSH 使用远程 Agent 模式。完整列表：docs/roadmap.md。

社区

• Discord： https://discord.gg/htPuQ5grg — 提问、展示与交流，以及获取会话阅读帮助。
• 讨论： https://github.com/shreyassaw5394/debuganything/discussions — 深入讨论想法和 RFC。
• 问题： 通过模板报告错误和适配器需求。想法请发到讨论区。
• 安全： 仅接受私密安全公告，详见 SECURITY.md。

贡献

main 受到保护：每项更改都必须通过拉取请求提交，并由代码所有者审核。 一个适配器大约有 80 行：声明 platforms/requires/tools，构建命令，通过 runCapped 运行命令，用纯函数解析，并通过 ResultBuilder 提交证据和发现项（没有证据时它会拒绝提交发现项）。将真实工具输出捕获一次并保存到 tests/fixtures/，然后用它测试解析器。操作指南见 CONTRIBUTING.md。

贡献者

所有提交过拉取请求的人。添加适配器、测试样本或文档，你的头像就会出现在这里。

npm、PyPI、GitHub 和 MCP Registry 的数据：bash scripts/stats.sh。

许可证与免责声明

MIT — 详见 LICENSE。Debug Anything 按**“现状”提供，不附带任何形式的保证**；对于因使用本项目而导致的服务中断、数据泄露或任何其他损害，作者和贡献者不承担任何责任。Debug Anything 会将观测工具附加到正在运行的软件上：仅观测你拥有或已获明确授权进行调试的系统——你须全权负责获得授权并遵守适用的法律和政策。观测并非没有代价（ptrace 会暂停目标进程；捕获内容和堆转储可能包含机密），发现项是自动化诊断结果，并非专业建议；Debug Anything 是由贡献者以个人身份开发的独立项目，与任何雇主或其协调使用的第三方工具均无关联。完整条款：DISCLAIMER.md。