Deadends.dev

🚀 deadends.dev

为AI编码代理提供结构化的失败知识。

deadends.dev 涵盖51个领域的2000多个错误条目。当AI编码代理遇到错误时，它们会在已知会失败的方法上浪费令牌。deadends.dev 可以告诉代理哪些方法不要尝试，哪些方法真正有效，以及接下来会出现什么错误。

网站：deadends.dev · MCP服务器：Smithery · PyPI：deadends-dev · API：/api/v1/index.json

🚀 快速开始

Python SDK 快速开始

from generator.lookup import lookup, batch_lookup, search

# 单个错误查找
result = lookup("ModuleNotFoundError: No module named 'torch'")

# 避免尝试的操作（节省令牌和时间）
for d in result["dead_ends"]:
    print(f"避免: {d['action']} — 失败率 {int(d['fail_rate']*100)}%")

# 实际有效的操作
for w in result["workarounds"]:
    print(f"尝试: {w['action']} — 成功率 {int(w['success_rate']*100)}%")

# result["url"] 是规范摘要页面的URL（例如 /python/modulenotfounderror/）
print(result["url"])

# 批量查找（一次处理多个错误）
results = batch_lookup([
    "ModuleNotFoundError: No module named 'torch'",
    "CUDA error: out of memory",
    "CrashLoopBackOff",
])

# 关键字搜索
hits = search("memory limit", domain="docker", limit=5)

CLI 快速开始

pip install deadends-dev
deadends "CUDA error: out of memory"
deadends --list  # 显示所有已知错误

✨ 主要特性

• 提供2000多个错误条目，涵盖51个领域。
• 为AI编码代理提供结构化的失败知识，避免在已知失败的方法上浪费令牌。
• 告知代理哪些方法不要尝试，哪些方法真正有效，以及接下来会出现什么错误。
• 提供多种工具和API接口，方便集成和使用。

📦 安装指南

pip install deadends-dev

要求：Python 3.10+

💻 使用示例

基础用法

from generator.lookup import lookup
result = lookup("ModuleNotFoundError: No module named 'torch'")
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} — fails {int(d['fail_rate']*100)}%")
for w in result["workarounds"]:
    print(f"TRY: {w['action']} — works {int(w['success_rate']*100)}%")
print(result["url"])

高级用法

from generator.lookup import batch_lookup, search
results = batch_lookup([
    "ModuleNotFoundError: No module named 'torch'",
    "CUDA error: out of memory",
    "CrashLoopBackOff",
])
hits = search("memory limit", domain="docker", limit=5)

📚 详细文档

MCP服务器

MCP服务器为AI编码代理提供8个工具：

本地部署（Claude Desktop / Cursor）

添加到 ~/.claude/claude_desktop_config.json：

{
    "mcpServers": {
        "deadend": {
            "command": "python",
            "args": ["-m", "mcp.server"],
            "cwd": "/path/to/deadends.dev"
        }
    }
}

托管部署（Smithery — 无需本地设置）

通过 Smithery 安装：

# Claude Code
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

# Cursor
npx -y @smithery/cli@latest install deadend/deadends-dev --client cursor

或者直接连接：https://server.smithery.ai/deadend/deadends-dev

示例响应

当代理遇到 ModuleNotFoundError: No module named 'torch' 时，lookup_error 工具返回：

## ModuleNotFoundError: No module named 'X' (Python 3.11+)
可解决: true | 修复率: 0.88

### 死胡同（不要尝试）:
- 使用系统Python执行 pip install X（70%失败）: 虚拟环境未激活

### 解决方法（尝试这些）:
- 创建虚拟环境，激活后再执行 pip install（95%有效）
- 使用 python -m pip install 而不是直接使用 pip（90%有效）

API端点

涵盖的领域（51个）

ErrorCanon数据格式

每个错误是一个JSON文件，包含以下内容：

{
    "error": { "signature": "...", "regex": "...", "domain": "..." },
    "verdict": { "resolvable": "true|partial|false", "fix_success_rate": 0.88 },
    "dead_ends": [{ "action": "...", "why_fails": "...", "fail_rate": 0.75 }],
    "workarounds": [{ "action": "...", "success_rate": 0.92, "how": "..." }],
    "transition_graph": { "leads_to": [...], "preceded_by": [...] }
}

AI编码代理集成 — 18种发现格式

deadends.dev 上的每个页面都包含18种格式的机器可读数据：

🔧 技术细节

开发

pip install -e ".[dev]"

# 完整流程（验证 → 生成 → 构建 → 测试）
python -m generator.pipeline

# 单个步骤
python -m generator.bulk_generate     # 从种子生成规范
python -m generator.build_site        # 构建静态网站
python -m generator.validate          # 验证数据和网站
python -m pytest tests/ -v            # 运行测试

贡献

将错误定义添加到 generator/bulk_generate.py 中，或直接在 data/canons/ 中创建JSON文件。

python -m generator.validate --data-only  # 提交前进行验证

变更日志

v0.7.0

• 扩展到51个领域的2089个错误条目（从20个领域的1028个条目扩展）。
• 添加了23个新领域：Android、API、Cloud、CMake、Communication、Data、Elasticsearch、Embedded、Flutter、gRPC、Hugging Face、Kafka、LLM、MongoDB、Nginx、OpenCV、Policy、PyTorch、Redis、ROS 2、Security、TensorFlow、Unity。
• 所有领域现在每个都有40个以上的错误条目。
• 修复了73个与自身签名不匹配的正则表达式模式。

v0.5.0

• 在 index.json、errors.ndjson 和所有SDK/MCP响应中添加了 page_url 字段 — 始终指向规范摘要页面 (/domain/slug/)，与特定环境的 url 字段不同。
• 查找SDK 的 url 返回值现在指向规范摘要页面，而不是特定环境的页面。
• MCP工具 (match_error, get_error_detail) 现在返回规范摘要URL。
• SEO修复：Atom提要、IndexNow提交、JSON-LD TechArticle和Open Graph标签都已更正为使用规范摘要URL。
• HTML模板中的错误链链接已更正为指向摘要页面，而不是无索引的特定环境页面。

v0.4.0

• 初始公开版本，包含20个领域的1028个错误条目。

📄 许可证

MIT（代码）· CC BY 4.0（数据）