deadends.dev

deadends.dev

阻止 AI Agent 重复已知失败——无论是在代码中，还是在现实世界里。

AI 助手常常在两类问题上出错：已知失败的代码修复，以及训练数据中从未接触过的特定国家现实规则。deadends.dev 现在涵盖这两类问题：

• 代码错误（2,089 条，涵盖 51 个领域）：当 Agent 遇到 ModuleNotFoundError、CUDA OOM、CrashLoopBackOff 等问题时，告诉它哪些方法不该尝试。
• 特定国家的死胡同（涵盖 52 个国家的 250 多条）：签证规则（ETA/eVisitor、NZeTA、电子签证、入境卡）、银行要求、法律红线（冒犯君主罪、§86a、Article 301）、文化禁忌（筷子插在米饭里、中国送钟、韩国用红笔写名字）、食品安全（各国自来水安全情况）、紧急电话号码、驾驶习惯（左侧通行）、住房合同——这些都是看似合理的通用答案在当地行不通的情况。

为何扩展？ 优秀的大模型基本上已能解决代码领域的死胡同问题。 日本印章要求、申根区 90/180 天计算、斋月营业时间、沙特禁酒令、印度的牛肉禁忌等特定国家的实际障碍，才是通用 AI 建议最容易出错的地方。代码库和架构完全相同；env 字段只需携带国家代码。

90% Precision@1 · 0.935 MRR · 数据质量仪表盘

网站： deadends.dev · MCP 服务： Smithery · PyPI： deadends-dev · API： /api/v1/index.json 代码仓库： https://github.com/dbwls99706/deadends.dev

为什么使用它？

不使用 deadends.dev	使用 deadends.dev
Agent 尝试 sudo pip install → 损坏系统 Python → 浪费 3 次重试	Agent 看到“死胡同：sudo pip——70% 的情况下会失败”→ 立即跳过
Agent 建议用户在东京餐厅给 15% 小费	Agent 知道日本不接受小费（culture/tipping-refused/jp）
Agent 起草提及泰国国王拉玛十世的社交媒体帖子	Agent 及时叫停：可能触犯泰国刑法第 112 条冒犯君主罪（legal/lese-majeste-article-112/th）
Agent 修复错误 A 后，被错误 B 搞糊涂	Agent 知道“A 有 78% 的概率会导致 B”→ 同时处理两者
Agent 建议未婚情侣在迪拜公开亲吻	Agent 提醒阿联酋公共道德法（legal/unmarried-public-affection/ae）

这与直接询问大模型有何不同？

• 确定性：相同的查询 → 每次都得到相同的答案。不会产生幻觉。
• 按国家划分：ID 格式为 {domain}/{slug}/{env}——env 保存国家代码（kr、jp、us、de……），因此同一禁忌可根据不同司法管辖区给出不同答案。
• 来源可靠：每条国家规则都引用政府网站、大使馆或可核实的报道。不会回答“根据一般知识……”。
• 经社区验证：根据真实结果报告更新修复成功率。
• 亚毫秒级：本地正则匹配，无需 API 往返。

实际限制（运维角度）

• 无法覆盖所有错误。遇到尚未收录的情况时，可通过 issue/PR/report_outcome 快速补充。
• 设计上优先解决实际问题（侧重死路/变通方案），而非深入讲解。
• 可靠性可能因领域/情况而异，因此建议对高风险变更与官方文档/供应商指南交叉验证。

快速开始（30 秒）

pip install deadends-dev
deadends "CUDA error: out of memory"

MCP 服务（Claude Desktop / Cursor）

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

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

或者通过 Smithery 安装（无需本地配置）：

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

MCP Unauthorized 快速解决指南（供人工参考）

如果看到 deadend: calling "initialize": sending "initialize": Unauthorized 错误，请按顺序执行/检查以下步骤。

1. 仅使用本地服务模式或远程（Smithery）模式中的一种

# 로컬 서버 확인 (정상 시 툴 목록이 출력됨)
python -m mcp.server --help

2. 检查 Claude Desktop 配置文件（cwd 必须是实际路径）

cat ~/.claude/claude_desktop_config.json

3. 直接测试运行本地服务

cd /path/to/deadends.dev
python -m mcp.server

4. 如果使用 Smithery 模式，请重新安装（修复令牌/配置异常）

npx -y @smithery/cli@latest uninstall deadend/deadends-dev --client claude
npx -y @smithery/cli@latest install deadend/deadends-dev --client claude

5. 最后，完全重启 Claude Desktop

# macOS 예시
osascript -e 'quit app "Claude"'
open -a Claude

提示：Unauthorized 通常由错误的 cwd、重复的服务配置（本地和远程同时配置）或过期的认证状态导致。

Antigravity（Google AI IDE）

添加为远程 MCP 服务——无需身份验证：

{
  "mcpServers": {
    "deadend": {
      "serverUrl": "https://deadends.dev/mcp",
      "type": "http"
    }
  }
}

注意： Antigravity 使用 serverUrl（而不是 url）。如果遇到 Unauthorized，请从 MCP Store 中移除所有现有的 deadend 条目，然后使用上述配置手动重新添加。有关一般故障排除，请参阅 Antigravity MCP 身份验证指南。

Python SDK

from generator.lookup import lookup, batch_lookup, search

# Single error lookup
result = lookup("ModuleNotFoundError: No module named 'torch'")

# What NOT to try (saves tokens and time)
for d in result["dead_ends"]:
    print(f"AVOID: {d['action']} - fails {int(d['fail_rate']*100)}%")

# What actually works
for w in result["workarounds"]:
    print(f"TRY: {w['action']} - works {int(w['success_rate']*100)}%")

# Batch lookup (multiple errors at once)
results = batch_lookup(["error1", "error2", "error3"])

示例响应

## ModuleNotFoundError: No module named 'X' (Python 3.11+)
Resolvable: true | Fix rate: 0.88

### Dead Ends (DO NOT TRY):
- pip install X with system Python (fails 70%): venv not activated

### Workarounds (TRY THESE):
- Create venv, activate, then pip install (works 95%)
- Use python -m pip install instead of bare pip (works 90%)

MCP 工具（11 个）

工具	描述
lookup_error	将错误消息与 2000 多种已知模式进行匹配
get_error_detail	按 ID 获取完整规范
list_error_domains	全部 54 个领域及其数量
search_errors	使用 TF-IDF 关键词搜索所有领域
list_errors_by_domain	获取某个领域中的所有错误
list_errors_by_country	获取指定 ISO alpha-2 代码对应的所有国家/地区级死路
get_country_summary	国家/地区级摘要（条目、修复率、领域分布）
batch_lookup	一次查找多个错误（最多 10 个）
get_domain_stats	领域质量指标和置信度等级
get_error_chain	遍历错误转换图
report_outcome	报告变通方案是否有效（用于更新成功率）

API 端点

端点	描述
/api/v1/match.json	轻量级正则匹配（适合放入上下文窗口）
/api/v1/index.json	包含元数据的完整错误索引（国家/地区规范条目包含 country 字段）
/api/v1/{id}.json	单个 ErrorCanon
/api/v1/countries.json	包含数量和更新时间的国家/地区索引
/api/v1/country/{cc}.json	单个国家/地区的聚合数据（一次调用即可返回该国家/地区的所有条目）
/api/v1/openapi.json	OpenAPI 3.1 规范
/api/v1/stats.json	按领域划分的数据集质量指标
/api/v1/errors.ndjson	NDJSON 流式输出
/llms.txt	面向大模型优化的列表（llmstxt.org）
/dashboard/	数据质量仪表板

覆盖领域（54 个）

代码错误领域（51）

领域	错误数	示例
Python	88	ModuleNotFoundError、TypeError、KeyError、MemoryError、RecursionError
Node	70	ERR_MODULE_NOT_FOUND、EACCES、EADDRINUSE、堆内存 OOM、ERR_REQUIRE_ESM
Docker	65	磁盘空间不足、exec 格式错误、绑定地址已被占用、健康检查
Kubernetes	61	CrashLoopBackOff、ImagePullBackOff、OOMKilled、RBAC 禁止访问、HPA
Git	60	推送失败、合并冲突、分离的 HEAD、stash apply、标签
CUDA	57	OOM、设备端断言、NCCL、cuDNN、张量设备不匹配
Go	54	空指针、未使用的导入、接口转换、切片越界
Java	54	NullPointerException、ClassNotFound、OutOfMemoryError、连接池
数据库	52	死锁、连接池、慢查询、复制延迟
AWS	51	AccessDenied、S3 NoSuchBucket、Lambda 超时、CloudFormation 回滚
.NET	50	NullReferenceException、LINQ 转换、DI 循环依赖、EF 并发
ROS 2	50	节点 spin、启动错误、QoS 不匹配、tf2 转换
TypeScript	49	TS2307、TS2322、TS2345、TS2532、TS7053
Rust	48	E0382 借用、E0308 类型不匹配、E0277 trait、E0106 生命周期
+ 37 个领域	各 40+	CI/CD、PHP、Terraform、网络、Next.js、React、pip、Android，……

按国家划分的真实世界领域（新增，持续扩展）

领域	涵盖内容	示例误区
visa	出行前授权、逾期停留、重新入境禁令	ESTA 90 天规则（US）、K-ETA（KR）、ETIAS/EES（申根区）、申根 90/180（DE）
banking	开户、KYC、外国人规定	需要 ARC（KR）、居留卡需满 6 个月（JP）、SSN/ITIN（US）
emergency	正确的紧急电话号码、交通	112 而非 911（DE）、999/101/111（UK）
medical	保险、处方药进口、保障范围	Shaho/Kokuho（JP）、NHIS 需满 6 个月（KR）、不符合 EHIC 资格（DE）、禁止进口 Adderall（JP）
legal	刑事责任、合同惯例	§86a 纳粹标志（DE）、第 112 条（TH）、第 301 条（TR）、禁酒（SA）、礼金（JP）
culture	礼仪、禁忌、社会规范	筷子插在米饭里（JP）、送钟（CN）、天安门相关话题保持沉默、用红笔写名字（KR）、bonjour（FR）
food-safety	饮用水、病原体、宗教禁忌	自来水（MX）、河豚执照（JP）、印度的牛肉、印度尼西亚的猪肉
communication	语言语域、术语	敬语（KR）、对越南战争的称呼（VN）、“gringo”（MX）、粤语与普通话（HK）
safety	驾驶、公共安全规范	靠左行驶（JP）、Autobahn 规则（DE）、鸣笛语言（IN）

数据质量

所有指标均可在数据质量仪表板公开查看：

• 2,204 条规范条目，涵盖 54 个领域和 39+ 个国家
• 基准测试：90% Precision@1、95% Precision@3、0.935 MRR（针对代码场景）
• 错误转换图：4,330+ 条边，连接相关错误
• 社区反馈循环：report_outcome 根据真实使用情况更新修复成功率
• 国家规范条目：每条均引用政府、使馆或监管机构的一手来源， 由人工审核（review_status: human_reviewed），不使用大模型批量生成

国家覆盖范围（截至 v0.10，共 52 个国家）

kr · jp · us · de · uk · fr · it · es · nl · ch · pt · ie · at · be · se · no · dk · fi · pl · gr · cn · hk · tw · th · in · vn · id · sg · ph · my · pk · bd · sa · ae · tr · il · ru · br · mx · ar · cl · co · pe · au · nz · eg · ma · et · ng · ke · za · ca

请参阅 国家/地区目录中心，或查看 /api/v1/countries.json，获取带数量统计的权威列表。

有关编写工作流、来源要求和置信度校准的信息，请参阅 docs/country-canon-guide.md。

贡献

完整详情请参阅 CONTRIBUTING.md。

• GitHub 自动采集运维方案：docs/GITHUB_DATA_COLLECTION_STRATEGY.md

• 自动采集周期：每 6 小时一次（每天 4 次），默认质量筛选条件：min_score=2

• 采集的数据仅作为候选内容，最终纳入前须经维护者审核

• 提交新的错误

• 报告解决方法的结果

• 尝试解决方法后，通过 MCP 使用 report_outcome

开发

pip install -e ".[dev]"

python -m generator.pipeline          # Full pipeline
python -m generator.build_site        # Build static site
python -m generator.validate          # Validate data + site
python -m pytest tests/ -v            # Run tests
ruff check generator/ tests/          # Lint
python benchmarks/run_benchmark.py    # Run benchmarks

SEO 检查指南（适用于所有页面）

以下命令可快速检查模板是否包含关键 SEO 信号。

python - <<'PY'
from pathlib import Path
files=[
  'generator/templates/index.html',
  'generator/templates/domain.html',
  'generator/templates/error_summary.html',
  'generator/templates/page.html',
  'generator/templates/search.html',
  'generator/templates/dashboard.html',
]
required=[
  '<title',
  'meta name="description"',
  'meta name="robots"',
  'link rel="canonical"',
  'meta property="og:title"',
  'meta name="twitter:card"',
]
for f in files:
    txt=Path(f).read_text()
    missing=[r for r in required if r not in txt]
    print(f'✅ {f}' if not missing else f'❌ {f} missing: {", ".join(missing)}')
PY

如需检查实际构建产物：

python -m generator.build_site
python -m http.server -d public 8080

然后在浏览器中检查以下内容：

• view-source:http://localhost:8080/search/
• view-source:http://localhost:8080/dashboard/
• canonical / og / twitter / JSON-LD 的有效性

更新日志

v0.10.0 - 扩展国家覆盖范围

• 覆盖 52 个国家的 250 多条国家规范（此前为 20 个国家的 56 条）：几乎所有受支持国家的紧急电话号码、现代签证入口（ETA/eVisitor、NZeTA、电子签证、数字入境卡）、药品进口规定、自来水安全、左侧通行安全和银行服务，均基于一手来源并经人工审核
• 按目的地交叉链接：国家摘要页面现在会链接到同一国家、其他领域的 dead ends（设有“{country} 中的更多 dead ends”版块），以加强主题相关的内部链接
• SEO：根据页面质量调整站点地图 <priority> 权重（国家页面／高证据页面排名更高）；JSON-LD 不包含空日期
• 样式：全站将 em dash 替换为连字符

v0.9.0 - 转向国家维度

• 新增维度：在代码错误之外，加入按国家划分的现实生活 dead ends
• 覆盖 20 多个国家的 56 条以上国家规范 - 签证、银行、法律红线、文化禁忌、食品安全、紧急电话号码、驾驶规范
• 新增 3 个领域：visa、banking、emergency（并扩展现有 legal、culture、medical、communication、food-safety、safety 领域的使用，加入国家环境分段）
• 各国落地页，位于 /country/{cc}/（例如 /country/jp/）
• generator.country_canon_template 辅助函数，用于编写新的国家规范，并验证环境分段、受众和司法管辖区元数据
• docs/country-canon-guide.md：来源标准（一手来源 > 大使馆 > 可靠媒体）、置信度校准、slug/正则表达式约定
• 架构未变更（以向后兼容的方式扩展枚举）；保留现有 2,089 条代码规范

v0.8.0

• 基准测试套件：20 种错误场景，Precision@1=90%，MRR=0.935
• 数据质量仪表板，位于 /dashboard/ - 指标透明公开
• 结果反馈闭环：report_outcome → 汇总统计 → 更新 fix_success_rate
• 使用分析：匿名工具使用情况跟踪（仅记录领域／匹配情况，不含 PII）
• 社区贡献：用于提交新错误和报告解决方法的 GitHub Issue 模板
• TF-IDF 搜索：通过平滑 IDF 评分提升相关性
• 错误转换图：物化图包含 4,330 多条边，并提供枢纽节点分析
• 9 个 MCP 工具（新增 report_outcome）

v0.7.0

• 扩展至 51 个领域，共 2089 条错误条目（此前为 20 个领域、1028 条）
• 新增 23 个领域
• 修复了 73 个无法匹配自身特征的正则表达式模式

v0.5.0

• 在 index.json、errors.ndjson 以及所有 SDK/MCP 响应中新增 page_url 字段
• 修复 canonical 摘要 URL 的 SEO 问题

v0.4.0

• 首次公开发布，包含 20 个领域的 1028 条错误条目

许可证

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

运维文档

• SEO 运维指南：docs/SEO_OPERATIONS_GUIDE.md
• PyPI 发布手册：docs/PYPI_RELEASE_MANUAL.md