Git 驱动、标准库检索：MisakaNet 的失败经验网络架构拆解
AI Agent 的失败经验大多死在某台机器的终端历史里。WSL 上 pip 超时怎么绕、NTFS 上 ChromaDB 为什么崩、FANUC 的报错码怎么读——这些结论都真实存在过，但只属于当时敲命令的那个人。MisakaNet 要把个人调试经验变成可搜索的共享知识，让一个 Agent 踩过的坑变成所有 Agent 的免疫记录。
值得拆解的是它为此付出的取舍：一个知识网络，没有服务器、没有数据库、没有守护进程，检索由纯 Python 标准库实现的 BM25 承担。
项目坐标与两层验证状态
按首页数据：作者 Ikalus1988，npm 包名 misakanet，Apache 2.0 许可，官网 misakanet.org，493 star，综合评分 70.7，最近上游提交 2026/9/19。当前规模为 393 条 canonical lessons（去重后）、333 个 nodes，覆盖 RAG、DevOps、Feishu、Fanuc、Network、Claude、MCP 等领域。
验证状态有两个字段，含义差得很远。一是实装验证通过（2026/9/16）：由 dsh-plugin-verify（GitHub Actions）在真实 dsh 环境里安装成功，不是静态推断。二是安装兼容性自动检查通过：npm 包已发布、engines 声明满足基线（检查记录为 misakanet @ 2.23.0、Node >=20.0.0），但页面同时注明这个结论来自程序自动检查、未经人工实机验证——能装不等于用着没问题。
前者是"装上了、安装动作真跑过"，后者是"看元数据推断应该能装上"，两者之间隔着一整类线上事故。另外页面的版本信息并不统一：自动检查写 2.23.0，安装段落写 2.30.2，装完最好自己核对一次实际版本。
为什么是 Git，不是数据库
它的存储层就是一条 Git 仓库：lessons 是 Markdown 文件，历史是提交记录，分发是 clone。分发成本因此归零——入门动作只有 git clone（官方口径 5 秒），没有镜像拉取、数据库初始化、端口规划；对比同类个人记忆方案的 Docker + PostgreSQL、Docker + Neo4j、Docker + Qdrant，差别不是"省事一点"，而是"这一小时能不能用上"。审计天然存在——每条 lesson 的增删改都留在提交历史里，数据库方案要实现同样能力得另写审计表。协作复用开源流程——PR、CI、review、合并都是现成的，不必自建权限体系。离线优先是结果而非功能——节点断网时仍能检索本地全部 lessons。
代价同样具体：Git 不以高并发写见长，多节点同时提交要靠 PR 队列串行化；检索只能在文件上做，拿不到数据库的全文索引能力；仓库体积随 lesson 线性增长，clone 会越来越慢。这些约束真实存在，只是在 393 条这个量级还没成为瓶颈。
BM25 用纯标准库：一次刻意的能力交换
检索层的取舍是全篇最有意思的地方：用 BM25 排序，但只用 Python 标准库。BM25 本身的要求并不轻——分词、词频、文档频率、平均文档长度，还要维护一份倒排结构；常规做法是引检索引擎或向量库进来，而"零依赖"把这条路封死了。
收益是部署面为零：没有编译依赖、没有 wheel 兼容问题、没有 x86 与 ARM 差异，同一份代码在 WSL、Windows、Linux、容器里行为一致。对"失败经验库"这种必须陪跑在最恶劣环境里的工具，零依赖不是洁癖而是使能条件——它的目标场景本来就是"你的环境已经出问题了"。
代价是能力上限被写死：没有向量检索就没有语义相似度，查"连接超时"不会自动召回只写了 timeout 的条目，同义词、缩写、中英混写都要求关键词能对上。说明里那句"搜索基于关键词匹配，不保证语义准确"不是谦辞，而是精确的能力边界描述。
这个取舍是自洽的：用召回质量换零部署摩擦，而零部署摩擦正是项目成立的前提。若哪天 lessons 涨到几万条、语义检索成为刚需，就需要重新审视；目前路线图上 v3.0 规划的是 Lesson 详情页、主题页与 Agent 框架，尚未涉及替换检索引擎。
E0–E4：把"可信"做成字段
开放失败经验库最大的风险不是内容少，而是内容不可信。v2.16.0 引入的 E0–E4 证据等级模型就是针对这一点的信任机制：同一个失败现象，是在真实环境复现并验证过，还是只是推测出的可能原因，可信度显然不同，等级越高越接近"已被真实环境证实"。
这和前面那两层验证是同一思路的延伸——把"可信"从模糊印象变成可标注、可比较的字段，使用者就能按等级取用：生产排障优先看高等级条目，技术调研时低等级条目也能提供线索。同版本发布的 Unsolved Map（失败覆盖率仪表盘）补的是另一半：把"哪些失败模式还没有答案"显式画出来，而不是让人误以为已知答案就是全部。
Lesson 的四段结构与 Lesson Lint 质量门
一条 lesson 就是一份 Markdown 文件，固定四段：问题 → 根因 → 修复 → 验证。结构本身就是设计，它逼贡献者回答四个层次不同的问题：现象是什么、为什么会这样、怎么解决、怎么确认真的解决了。缺最后一段读者只能盲信，缺第二段读者遇到变体就会再踩一次。
v2.17.0 引入的 Lesson Lint 是这套格式的自动质量门，检查三类问题：断链、重复标题、缺少 frontmatter。三项都不是文风问题，而是直接破坏知识网络可用性的结构缺陷——断链让引用失效，重复标题制造检索歧义，缺 frontmatter 让条目无法被正确归类。放进贡献流程看就完整了：遇到真实失败 → 记录问题/根因/修复/验证 → queue_lesson.py 提交 → CI 自动检查质量分数、DCO、格式 → 合并后进入知识库，所有节点可搜索。
一个常见误用：Lesson 不是 Skill
Skill 教 Agent 怎么做事；Lesson 教 Agent 以前哪里失败过、下次别再踩。 Lesson 是失败经验与排错知识，粒度是一个具体 failure pattern，时机是出错前预防、出错后排查；Skill 是可执行能力或工作流，在执行任务时调用。定位搞混就会用错地方。
工程判断
MisakaNet 的设计是自洽的：用 Git 换掉服务端，用标准库换掉检索引擎依赖，用证据等级与 Lint 换掉人工背书，代价是语义召回与并发写入能力。它解决的不是"让 Agent 更聪明"，而是"让 Agent 不在同一个地方摔第二次"——这个目标对基础设施的要求恰好很低，所以极简技术栈在这里成立，而不是妥协。
评估时建议按两层验证分别打分：实装通过说明它能跑起来，自动检查通过说明元数据没问题，而后者明确未经人工实机验证。
想继续翻同类插件的可以直接看清单：https://dpharness.com/top
三个 Agent 别再踩同一个坑：MisakaNet 落地一周的完整实践
我们的团队有一套不算复杂但很难管的组合：一台本地开发机上的 Agent、CI 流水线里的 Agent、还有云上跑定时任务的 Agent。它们干的是同一类活，踩的也是同一类坑——只是彼此不知道。
先说清起因：WSL 上 pip install 稳定超时，NTFS 挂载卷上 ChromaDB 直接崩；CI 里 DCO 签名检查失败，PR 被反复拒；github token 401 出现三次，每次都是不同的人重新查一遍。第一个月我们的处理方式是群里问、有人答、答案沉进聊天记录，下个月换个人再问一遍。
这篇写的是我们把它换成 MisakaNet 之后，一周内实际做的事。
起点：并行踩坑的浪费有多大
把失败复盘一下就会发现，浪费不在"解决问题"本身，而在同一份解法被重复推导了多次。第一次遇到 pip install 超时的同学花了很长时间定位到源和超时参数，第二次换了个人，照样从头来。云上那台机器又一次，因为那台机器上没人看到群里的截图。
这里最合适的类比是"排错知识"，不是"执行能力"。前者是典型的知识沉淀问题，后者才需要能力封装。MisakaNet 里区分得很明确：Lesson 记录失败经验与修复路径，Skill 才是可执行的能力。我们要找的是前者。
四种接入方式，分别适合谁
它提供了四条入口，能力边界不一样，选之前先看使用者是谁。
| 方式 | 怎么进 | 适合谁 |
|---|---|---|
| Remote MCP（推荐） | 在 MCP 配置里填远程端点与 Bearer Token，之后直接问「搜索 MisakaNet 关于 database locked」 | 不想 clone、希望 Agent 实时调用检索 |
| CLI | pip install misakanet-core 后跑 python3 search_knowledge.py "GitHub token 401" | 人自己查、写批处理脚本 |
| Web | 打开 misakanet.org/search 直接搜 | 临时查一次、不写代码的同事 |
| dsh 插件 | 装进 DeepSeek Harness，出错时由 Agent 主动查 | 日常就在 dsh 里干活的团队 |
我们的分工是混合的：人不写代码时用 Web，排查脚本里嵌 CLI，Agent 走 Remote MCP 加 dsh 插件。两个 Agent 侧的开销都落在配置上，不落在代码里。
dsh 插件的两条安装路径值得留意，因为我们两条都试过：
dsh plugin --profile web add misakanet # npm 路径，最省事
dsh plugin add git+https://github.com/Ikalus1988/MisakaNet.git # git 路径，同一 bundle
mkdir -p ~/.dsh/skills # SKILL 必须落到这里，dsh 才会扫描到
cp -r skills/misakanet ~/.dsh/skills/
最后两行是让 failure-memory SKILL 可被发现的关键动作。dsh 扫描的是 ~/.dsh/skills 与项目的 .dsh/skills，克隆下来的 skills/misakanet 不会自动出现在这两个位置。
落地顺序：我们一周内的安排
第一天只做一件事——把已知的失败经验查出来，不做任何自动化。团队里三个人分别用 Web 和 CLI 搜「pip install timeout」「DCO」「token 401」这类关键词，把命中的条目读一遍，确认哪些对得上我们的环境。这一步把"这个库有没有我们要的东西"变成了具体结论。
第二天才接 Agent 侧的入口。Remote MCP 的配置很轻，麻烦的是 Token 要放进凭据管理而不是写进仓库；dsh 插件那条路径按上面四条命令走完，验证方式是让 Agent 在出错的场景里主动搜一次，看它能不能带回条目。
第三天起进入常态使用，也就是下面这两段。
把 lesson 当失败记忆层：出错前与出错后
出错前用它预防。 我们形成了两个习惯动作。一是接手新环境时先搜一遍该环境的典型失败（WSL、NTFS 挂载、CI 容器），把相关条目当检查清单过一遍，很多坑在踩之前就能绕开。二是改动流水线配置之前先搜，尤其是 DCO、依赖安装这类我们已经栽过的环节。
出错后用它排查。 关键动作只有一个：先搜原始报错，再动手改配置。以前的做法是边猜边试，试出一个能跑的组合就收工，结果没人知道真正的原因，下次换台机器又要重来。先搜一次的成本极低，而它常常直接给出根因，而不是一个"碰巧能过"的配置。
有个使用细节值得单独说：检索是 BM25 关键词匹配，不保证语义准确，所以查询词的选择直接影响结果。报错原文里最独特的那个 token——报错码、库名、命令名——才是好查询词；写「连接超时」这种泛词，召回质量会明显下降。这条我们自己试出来的经验，后来反过来写成了一条 lesson。
贡献一条 lesson 的完整流程
我们的第一条贡献是 github token 401 的排查路径，流程如下。
先用四段结构把内容写出来：问题（可复现的现象）、根因（为什么 token 会失效）、修复（具体步骤）、验证（怎么确认修好了）。第二段和第四段最容易偷懒，但恰恰是它们决定这条经验对别人有没有用——缺验证段，读者只能盲信。
然后用脚本提交：
python3 scripts/queue_lesson.py --title "GitHub token 401 排查" --domain "DevOps" "..." # 提交一条 lesson
接下来是 CI 这道门：自动检查质量分数、DCO、格式。我们第一次提交就被 DCO 卡住，因为提交没带签名；质量分数和格式检查则要求 frontmatter 完整，缺了会被拦下——这也是 Lesson Lint 的三项检查（断链、重复标题、缺少 frontmatter）在起作用。合并之后，这条经验就进了知识库，所有节点都能搜到。
一些边界与判断
用下来有三点需要提前知道。
库里没有的，照样要自己趟。 393 条 canonical lessons、333 个 nodes 覆盖的是大家踩过的坑，你环境里的独有问题未必有人遇过。它是加速器，不是保险。
lesson 是社区贡献，用之前要读一遍。 尤其涉及改动系统配置、凭据处理的条目，先判断是否适合自己的场景，再在自己环境里验证。我们内部的约定是：任何条目在落地到生产流水线前，必须有人在自己的沙箱里复现过一次验证段。
它不替代排查能力。 它最大的作用是让你不必从零推导，而不是让你不必思考。
一周下来，最直观的变化是"同一个坑不再有三个人分别踩"。更具体一点：新同学上手的第一个问题从"这个报错你们谁见过"变成了"我先去库里搜一下"。
想看更多同类插件与汉化清单的，可以走这份汇总：https://dpharness.com/top