把"先搜失败经验"嵌进流程：MisakaNet 的四个触发点与一条回流闭环
一个知识库装好之后最常见的结局是：第一次用得很新鲜，之后再也想不起来打开它。问题不在工具，而在它没有被放到流程的某个位置上——需要它是"想起来才做"的事，而不是"到这里就必须做"的事。
这篇讲的就是位置。它不介绍功能，只回答一个问题：这条命令应该出现在工作流的哪一步、由谁触发、失败之后怎么闭环。
一条原则：把查询放在动手改之前
所有插入点都来自同一条原则——在修改任何配置之前，先花十秒搜一次原始报错。理由是成本结构：搜一次的成本是十秒，猜错的成本是"试出来一个能跑的组合、但没人知道真正原因"，下次换台机器重新来过。
反过来说，事后补搜的价值就小很多：问题已经解决了，动力也就没了。所以插入点的选取标准不是"哪里方便"，而是"哪里能拦住盲目试错"。
触发点一：环境就绪后的第一条命令
新机器、新容器、新的 CI runner、换了一个挂载类型——这类时刻是失败经验最密集的时刻，也是最容易一次性踩一堆坑的时刻。
动作可以很小：环境初始化脚本的末尾，按环境特征搜三到五个关键词（系统与版本、文件系统类型、包管理器、编排方式），把命中的条目当检查清单过一遍。它替代不了测试，但能在动手前就知道"这个组合有已知的坑"。
这个动作有个额外好处：它把"环境准备了没有"和"这个环境有什么已知问题"合并成一步，不需要额外记一个地址去翻文档。
触发点二：报错原文到手的那三十秒
这是主触发点，也是最需要纪律的地方：先搜，再改。
更关键的是搜什么。它的检索是 BM25 关键词匹配，官方明确写着"不保证语义准确"，所以查询词的选择直接决定结果好坏。经验规则有三条：
- 抄原文里的独特 token：报错码、库名、命令名、文件名，这些词在语料里区分度最高；
- 别用泛词：写"连接超时""依赖装不上"这种描述性短语，召回会明显变差，因为它对每条 lesson 都"沾一点边"；
- 保留原始语言：报错是英文就抄英文，不要先翻译再搜，翻译会丢掉最独特的那个词。
如果搜不到，不要停在这里——这恰好是下一条回流闭环的输入。
触发点三：流水线红掉时的分流
CI 失败有很多种，其中一类是"你改的东西没错，但流程要求你没满足"。DCO 签名、格式检查、质量分数这三道门就属于这一类：PR 被拒的原因是流程性的，而不是逻辑性的。
这类失败最适合先搜一遍。原因很实际：流程性失败的信息量很低（多半只有一行检查名），但解法很固定，查一次就能拿到完整步骤，比自己翻文档快。而贡献侧的自动检查还有三项专门的质量门——断链、重复标题、缺少 frontmatter，同样是查到就照做、查不到就试错的类型。
在团队里，这一步可以做成一条约定：凡是流水线报错，先在群里贴出搜索命中的条目再讨论。讨论的起点从"你们谁见过"变成"这条经验适不适用"。
触发点四：每周复盘一次，把口头经验转成 lesson
前三个触发点在"取"，这一个在"存"。没有存的动作，池子不会长，网络效应也就无从谈起。
做法很简单：每周固定花一点时间，把这一周里被反复讨论、被重复排查、被临时贴到群里的排错结论挑出来，按固定四段结构写成条目——现象、根因、修复、验证。四段里最容易偷工减料的是根因和验证：缺根因，别人遇到变体还会再踩；缺验证，读的人只能盲信。
写完提交走脚本，之后由 CI 检查质量分数、DCO 与格式，合并后就对所有节点可见。这里有一个设计细节值得一提：检索有本地额度限制，实测连续查询几次后会用尽，而贡献一条 lesson 正好可以恢复额度。这个机制把"取"和"存"绑成了一个闭环——用得多的人，自然会被推着写一点回去。对团队来说，它比任何"请积极贡献"的口号都有效。
落地节奏：一次只固定一个触发点
四个触发点不必同时上。每一个都要改动别人的既有习惯，一起推行通常活不过两周。
建议先只钉住一个，多数团队选"报错后先搜"那个，因为它的收益最容易被感知。跑几周之后再看：如果没人再用，原因多半不在工具，而在于它始终只是口头建议、没被写进排错规范；如果它自己活了下来，再把环境初始化与流水线分流补上，顺序反过来风险小得多。
Agent 侧：让它在报错路径上自己查
人会被流程拦住，Agent 不会。所以人这一侧的触发点之外，还要给 Agent 侧的入口。
dsh 插件那条路径里有两个不同的面，作用位置不一样：SKILL 面负责让 Agent 知道"遇到失败先去查"这个动作，需要把仓库里的 skills 目录放到 dsh 会扫描的用户级或项目级位置，否则它不会被发现；工具面提供真正可调用的检索能力，走 Remote MCP 时它指向远端服务，因此要在配置里带上 Bearer Token，凭据应当放在凭据管理里而不是提交进仓库。
两者配好之后，验收方式很直接：在一个已知会报错的环境里跑一次任务，看 Agent 是否在动手改配置之前主动发起检索。它如果只是把错误信息复述给你，说明入口没接上。
三条别踩的边界
别把 lesson 当运行手册。 条目带证据等级分级（E0–E4），等级高低代表可信程度不同，页面并没有承诺每条都达到高等级。照搬一条命令到生产上执行之前，先看等级，再在自己的沙盒里复现一遍——官方也明确建议在沙盒环境中运行 Agent。
别默认社区条目都对。 库里的内容是社区贡献，使用前请审查，尤其涉及改动系统配置、处理凭据、动数据库的条目。团队的约定可以是"落地到生产前必须有人本地复现过一次"。
别把节点数当覆盖度。 333 个节点说明有多少人在用，393 条去重条目才说明有多少知识。评估覆盖时看的是条目数和方向分布，不是节点数。
一页集成清单
把上面的内容落到可执行层面，是这样一份清单：
1. 环境初始化脚本末尾，按环境特征搜一轮已知失败；
2. 在排错规范里写下"先搜原始报错，再改配置"，并给出查询词三条纪律；
3. 流水线失败时的第一动作改为搜索，讨论从命中条目开始；
4. 每周复盘一次，把反复出现的排错结论写成四段式 lesson 并提交；
5. Agent 侧把 SKILL 放进可被发现的位置，或接上 Remote MCP 并管理好 Token；
6. 引用任何条目到生产前，先看证据等级、再本地复现。
六条里前三条是"取"，第四条是"存"，后两条是"边界"。它们不要求任何一方改变现有工作方式，只是往已有的步骤里插了一小段动作——这也是它最容易被接受的地方。
想看看同类插件各自适合插在流程的哪个位置，可以从这份清单开始比较 https://dpharness.com/top