这份清单按「现象 → 原因 → 解决方案」组织，目标不是讲清原理，而是让你在卡住的那一分钟里最快找到下一句该敲什么。MisakaNet（失败经验库）是 Git 驱动、零依赖优先的 AI Agent 失败经验知识网络，作者 Ikalus1988，仓库在 GitHub 的 Ikalus1988/MisakaNet，493 star，Apache 2.0 许可，官网 misakanet.org，当前 393 条 canonical lessons、333 个 nodes，检索为 BM25 关键词匹配、纯 Python 标准库实现。
故障集中在两段：装的那一段，和往库里写内容的那一段。前者多半是理解偏差，后者多半是被自动检查挡回。
先过一遍前置，别在环境上浪费判断力
两类前置条件经常被跳过，跳过之后的所有报错都会指向错误方向：
-
运行环境：仓库声明 Node 要求 >=20.0.0（基线 Node 22.19 满足），另外「零依赖」指的是只用 Python 标准库，所以 python3 必须在 PATH 里；
-
版本预期：页面自身存在两处不一致的版本号——安装兼容性检查显示 misakanet @ 2.23.0，安装段落写的是 misakanet@2.30.2。不要靠页面文字推断本机装了什么。
