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（數據）