WTF（为什么失败）
克劳德代码中用于事故排除的飞行记录器。WTF捕获 将每次工具调用和手动观察都保存到一个持久的SQLite数据库中 在上下文压缩中幸存下来，然后通过背景丰富原始条目 分类器被提取到一个精炼的时间轴中。
先决条件
- 克劳德代码 CLI(
claude) jq（JSON处理器）curl或wget- Bedrock的AWS证书（可选——启用背景分类器）
安装
curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash这将为您的平台下载预编译的二进制文件，并安装 PostTool使用钩子，并注册MCP服务器。无需克隆或运行时。 技能(/wtf, /wtf now, /wtf happened, /wtf imout)由以下人员交付 claudecode工作流.
验证安装：
curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --check安装特定版本：
curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --version v1.0.0开发安装
如果你在WTF服务器上工作，克隆仓库并使用本地 安装程序（需要 包子):
git clone https://github.com/Wave-Engineering/mcp-server-wtf.git
cd mcp-server-wtf
./scripts/install.sh快速开始
# Start troubleshooting
/wtf
# Investigate the issue... Claude records tool calls automatically
# Get the distilled timeline
wtf_happened
# Add your own observations
/wtf now "DNS resolver returning stale records"架构概述
WTF是一个三层系统：
/wtf, /wtf now Skills (user-facing entry points)
|
v
wtf_now, wtf_happened MCP Server (journal storage, retrieval,
wtf_freshell background classification)
^
|
PostToolUse hook Auto-capture (every tool call -> JSONL queue)第1层——技能： /wtf 启动故障排除会话并激活 飞行记录器模式。 /wtf now 添加手动日记账条目。
第2层——MCP服务器： Bun+TypeScript服务器公开了四种工具 stdio传输。管理SQLite数据库，接收钩子队列，并运行 背景分类器（Claude Haiku通过AWS Bedrock）将条目分类为 行动、面包屑、理论或噪音。
第3层——PostToolUse钩子： 一个在每个Claude代码上启动的shell脚本 工具调用，提取相关字段，截断大值，并附加JSON 排队 .wtf/hook-queue.jsonl 用于摄入。
用法
开始会话
/wtf将之前的事件存档，并创建一个新的事件。提示选择 标题，然后将克劳德置于飞行记录器模式，在该模式下进行重要观测 自动记录。
记录观察结果
/wtf now the health endpoint is returning 503s
/wtf now "theory: connection pool exhaustion under load"
/wtf now checked nginx logs — 502s started at 14:32在日记账中添加手动条目。分类由后台处理 分类器。
获取时间线
打电话给 wtf_happened MCP工具（Claude可以直接调用它，或者你可以问 对于它）：
wtf_happened # summary (max 50 lines)
wtf_happened { detail: "full" } # all entries返回一个经过提炼的Markdown时间线：
## WTF Summary -- DNS Resolution Failure
**Duration:** 45 min | **Entries:** 127 raw, 34 distilled | **Status:** active
1. [12:03] BREADCRUMB -- Health endpoint returning 503s intermittently
2. [12:05] THEORY -- Connection pool exhaustion, idle timeout set to 0
3. [12:08] ACTION -- Set DB_POOL_IDLE_TIMEOUT=30s in .env暂停录制
/wtf imout暂停飞行记录器而不丢失数据。切换到时有用 非故障排除工作。钩子仍然会发出声音，但条目会被过滤。
生成Runbook
wtf_happened 还将runbook骨架写入 .wtf/runbook.md 这可能是 提炼成可重复使用的剧本。
清理/重新开始
wtf_freshell将当前事件存档并开始新的事件。以前的条目是 保存在数据库中。
配置
数据目录
所有运行时数据都存在于 .wtf/ 相对于项目根（gitignored）：
.wtf/
wtf.db SQLite database (WAL mode)
hook-queue.jsonl Hook queue (consumed by MCP server)
runbook.md Generated runbook skeleton可调值
| 参数 | 默认值 | 位置 |
|---|---|---|
| 队列轮询间隔 | 2000毫秒 | queue.ts |
| 分类器轮询间隔 | 5000毫秒 | classifier/worker.ts |
| 分类器速率限制 | 2000ms | classifier/worker.ts |
| 钩子截断限制 | 4096字节 | scripts/hooks/wtf-post-tool-use.sh |
| 汇总行上限 | 50行 | tools/happened.ts |
MCP服务器注册
远程安装程序注册已编译的二进制文件：
claude mcp add --scope user --transport stdio wtf-server -- ~/.local/bin/wtf-server开发安装程序直接注册Bun源代码：
claude mcp add --scope user --transport stdio wtf-server -- bun /path/to/mcp-server-wtf/index.ts吊钩配置
PostToolUse钩子在中配置 ~/.claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"type": "command",
"command": "/absolute/path/to/scripts/hooks/wtf-post-tool-use.sh"
}
]
}
}卸载
如果通过远程安装程序安装：
curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --uninstall如果从本地克隆安装：
./scripts/install.sh --uninstall两者都删除了MCP服务器注册和挂钩配置。这 每个项目 .wtf/ 数据目录被保留（它们包含事件 历史）。要删除它们，请执行以下操作：
rm -rf .wtf/许可证
麻省理工学院——见 许可证.