这份清单按「现象 → 原因 → 解决方案」组织，目标不是讲清原理，而是让你在卡住的那一分钟里最快找到下一句该敲什么。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。不要靠页面文字推断本机装了什么。
一分钟现象索引
| 插件在列表里，但工具列表没有 mcp__misakanet__ | 安装形态不含 MCP 服务器 | 坑一 |
| 装完了，Agent 行为跟没装一样 | SKILL 不在扫描路径上 | 坑二 |
| 提交的 lesson 被自动检查挡回 | 触发 Lesson Lint 三项检查 | 坑三 |
| PR 状态是失败，理由与签名有关 | 提交缺 DCO 签名 | 坑四 |
安装阶段
坑一：dsh 里翻不到 mcp__misakanet__ 开头的工具
现象：插件装好了，dsh plugin list 里也能看到条目，但会话里让它调用实时工具时，工具名始终补不出来，只有 skill 与命令行两条路能用。反复检查配置，配置本身没问题。
原因：这是安装形态决定的能力差，不是配置写错。npm 包只包含 skill 与命令行面；那批以 mcp__misakanet__ 打头的工具由仓库自带的 python MCP 服务器提供，只在 git+ 方式安装时才随包存在。你装的那一半本来就不含它们，怎么配都找不到。
解决方案：先定需求再定装法。只需要「读到失败经验 + 命令行搜索」，npm 那条路足够；明确要用实时工具，就换成从 git 源安装。不想改安装方式的话还有第三条路：在 profile patch 里把 dsh-mcp-client 指向远端端点 https://misakanet.org/mcp，具体示例在仓库 docs/maintenance.md 的 dsh bundle 章节里。
坑二：插件装上了，failure-memory SKILL 却像不存在
现象：插件已登记，命令行搜索也正常，但 Agent 从不主动去查失败经验，处理报错的流程和没装之前一模一样。
原因：dsh 只在两个位置扫描 SKILL——用户级的 ~/.dsh/skills 和项目级的 .dsh/skills。仓库里的技能包放在自己的 skills/misakanet 目录下，位置对不上扫描路径，因此永远不会被加载。插件安装动作并不会替你做这次搬运。
解决方案：手工把它放进去，然后重启会话再验证：
cp -r skills/misakanet ~/.dsh/skills/ # 把技能包搬进 dsh 的扫描路径
若只想让单个项目生效，就复制到该项目下的 .dsh/skills。验证时不要只看插件列表里的状态，那个字段反映的是插件登记，不是 SKILL 是否被加载——要看 Agent 遇到报错时会不会主动发起一次检索。
到这里，安装侧的常见故障就覆盖完了。想把同类插件的中文清单与安装形态一次性看全，可以对照这份整理：DeepSeek Harness 插件推荐 · 精选 Top 榜（附下载量与安装命令）
贡献阶段
坑三：lesson 提交后被自动检查挡回
现象：按四段结构写完了内容，也用 scripts/queue_lesson.py 提交了（–title 与 –domain 传元信息，末尾位置参数放正文），结果没有进入知识库，状态停在检查未通过。
原因：合并前有一道自动质量门。Lesson Lint 会检查三类结构缺陷：断链、重复标题、缺少 frontmatter。这三项都不是文风问题——断链让引用失效，重复标题制造检索歧义，缺 frontmatter 会让条目丢掉领域、证据等级这类排序依赖的元数据。此外 CI 还会检查质量分数、DCO 与格式。
解决方案：把检查项当提交前自检清单用。写完先做三件事：确认 frontmatter 字段齐全、确认正文里的链接都能打开、确认标题在库内没有同名的。四段结构（问题 → 根因 → 修复 → 验证）里最容易偷工减料的是「验证」——省掉它，读者只能盲信结论，这条经验的价值会掉一大截。
坑四：PR 被 CI 拒，理由指向签名
现象：内容没问题、格式也补齐了，CI 仍然失败，提示与签名相关。
原因：贡献流程要求提交带 Signed-off-by 行，也就是 DCO 签名。缺少这一行时，代码内容再正确也过不了这一关。这不是质量判断，而是贡献流程的合规要求。
解决方案：重新提交时带上签名参数：
git commit -s # 提交时自动附加 Signed-off-by 行
如果已经产生了没有签名的提交，用 DCO 工具补签后再推送即可，不必重写整段历史。养成习惯之后，这类失败基本不会再出现。
排查顺序建议
按下面四步走，能避免在错误方向上花时间：
先确认前置：python3 可用、Node 版本达标、所选入口的依赖已按对应方式装齐；
再看安装形态与 SKILL 落地位置——工具找不到查形态，行为没变化查扫描路径；
用一条报错原文的关键词做验证查询，确认检索链路本身是通的（关键词匹配，别用整句自然语言描述）；
若问题出在贡献环节，按 Lesson Lint 三项 + DCO 签名的顺序逐条核对，这些都过了再看内容质量。
小结
这份清单里的四类故障有个共同点：它们都不是代码缺陷，而是「形态问题」和「流程问题」。找工具的失败源于选了不含它的安装形态；SKILL 不生效源于位置没落在扫描路径上；提交被拒则源于两道自动检查各自守着一类硬性要求。把这几条边界记住，剩下的时间就可以花在真正有价值的事情上——把踩过的坑写清楚一条。
需要完整的中文插件清单与接入形态对照，文末这份整理可以直接拿走：DeepSeek Harness 插件推荐 · 精选 Top 榜（附下载量与安装命令）
