MisakaNet 失败经验库
零依赖、Git 管理的 AI Agent 调试失败经验库：让 Agent 搜索已验证的故障修复课程，不再重复调试同一个错误。
按维度查看评分与理由
SECURITY.md 披露公共 PAT（仅 Issues:write、单仓库、建议30天轮换），fatal-guard 有令牌脱敏测试（redact-compliance.js），CI 扫描危险模式，lesson 执行前建议沙箱审查——最低权限与确认机制有据可查但依赖声明；扣分：PAT 'hex-encoded in HTML' 是脆弱设计，lesson 中的修复命令本身是社区内容、无强制人工确认门槛。自动草稿 workflow 推送分支并建 PR 属外部写操作，虽有审核环节；回滚仅有 git 天然能力、无显式回滚流程；发布者身份未验证，lesson 贡献者在提供的文件中无逐条署名。
fatal-guard 的 CLI 合同测试和崩溃场景测试显示错误信息具体且可操作（ENOENT/EACCES 区分、超时提示）。扣分：严重的自相矛盾——README 标榜 v2.16.0 且'零依赖'，而 package. 为 2.28.1、pyproject 为 2.29.0，requirements.txt 明确列出 mcp/schema/pyyaml 依赖，'zero-dependency' 仅对核心引擎成立，文档未一致说明；所引 docs（troubleshooting 等）不在证据内。
受众与场景描述非常充分：开发者、Agent 构建者、贡献者、评测者各有入口，'lessons vs skills' 边界表和非目标表清晰划定能力边界。扣分：触发精度依赖 Agent 自觉调用搜索，无明确触发规范；环境声称覆盖 Cursor/Claude Code/Codex、Docker，但具体适配配置未在证据文件中出现。
信息架构极佳：路径图、命令表、领域示例、FAQ/ROADMAP/SECURITY/LIMITATIONS 结构完整；LICENSE 为完整 Apache-2.0。扣分：版本管理混乱——README 展示 v2.16.0 特性而包文件为 2.28.1/2.29.0，三处版本不一致且无 CHANGELOG 文件在证据中；安装说明多为外链（docs/quickstart.md 不在证据内），示例与 FAQ 同样仅以链接存在，无法核实内容。
lesson 结构（问题→根因→修复→验证）输出可用性良好，BM25+RRF 检索、零依赖核心对成本收益有说服力。扣分：实际检索质量、289 条 lesson 的覆盖与正确性均无法从证据文件验证，价值主张大量依赖宣传性对比图（'30+ min vs 0.02s'）而非可核查数据。
fatal-guard 包有真实测试文件可交叉印证（脱敏、CLI 行为），chromadb 移除决定附有具体 GHSA 理由可追溯。扣分：核心统计（289 lessons、59 nodes、98 bench tasks）无证据内数据支撑；README 中'2026 Q2/Q3 已完成'的未来日期路线图与事实陈述混杂，宣传语与可验证事实未分离；大量关键文档（ARCHITECTURE、LIMITATIONS、mcp docs）只以链接出现。
- 低信任：不要直接执行检索到的 lesson 修复命令，务必先人工审查并在沙箱中运行。
- 仓库版本自相矛盾（README v2.16.0 vs package. 2.28.1 vs pyproject 2.29.0），'零依赖'仅对核心成立，安装 mcp/schema/pyyaml 时需另行评估供应链风险。
- 公共注册表单内嵌 PAT（即便 scope 受限）属已知攻击面，确认其轮换机制是否实际执行。
- auto-draft workflow 可经 repository_dispatch 远程触发并自动建 PR，使用前评估其滥用可能。
- 发布者未经企业注册表验证，核心指标（289 条 lesson 等）无独立证据。
这个 Agent 能做什么，适合哪些场景？
MisakaNet 是一个面向 AI 编码 Agent 的共享失败记忆库，收录 383 条以上按证据分级（E0-E4）的失败修复课程，内容覆盖 rag、devops、docker、fanuc 等领域。每条课程都是 Markdown 文件（问题→根因→修复→验证），以 Git 仓库为唯一事实来源，本地检索使用纯 Python 标准库实现的 BM25 关键词搜索，无向量数据库、无嵌入模型、无外部依赖。它提供多种接入面：本地 stdio MCP 服务器（scripts/mcp_server.py，7 个工具）、远程 HTTP MCP（https://misakanet.org/mcp，基于 Cloudflare Worker + D1 + KV）、CLI（search_knowledge.py）、PyPI 包（misakanet / misakanet-core）以及 DSH 适配器。Agent 遇到错误时可搜索课程获取修复路径；找不到匹配课程时可通过 misakanet_submit_intake 无账号提交脱敏故障报告，经维护者审核后转为课程。周度基准测试显示，注入课程上下文可将 llama-3.3-70b 的命中率从 42% 提升到 73%。项目采用 Apache-2.0 许可证，部署边界明确：本地 git clone 即可无限使用，远程匿名访问限每日 5 次免费读取。
MisakaNet 的核心操作是检索与沉淀失败修复知识。读取：扫描 lessons/ 目录下的 Markdown 课程文件（含问题、根因、修复、验证四段），通过 engine.py 的 BM25 引擎做关键词检索。运行：python3 scripts/mcp_server.py 启动本地 stdio MCP 服务器，暴露 misakanet_search、misakanet_get_lesson、misakanet_submit_intake、misakanet_write_lesson、misakanet_preflight、misakanet_register、misakanet_me_events 七个工具；或 python3 search_knowledge.py "查询词" 直接命令行搜索。调用：远程模式下请求 https://misakanet.org/mcp（Cloudflare Worker，D1 存储课程与脱敏数据，KV 做限流，intake 转为 GitHub Issue）。产出：搜索结果（标题+相关性得分）、注册返回的 node_id + token、经审核后的新课程。贡献路径：维护者评审 intake Issue 后将失败报告转为草稿课程，PR 需通过 50 个 CI 工作流的门禁。
- 使用 Claude Code / Cursor 的开发者在 Agent 卡在已知错误（如 pip 超时、DCO 签名失败、数据库锁）时，先搜索课程库获取已验证修复路径，避免重复调试。
- Agent 框架开发者为自己的工具链接入失败记忆层：本地 git clone 后跑 stdio MCP，零依赖即可让 Agent 复用全网沉淀的故障课程。
- 无法访问 GitHub 或不想注册账号的远程 Agent，通过 curl 调用 misakanet.org/mcp 匿名搜索，或用 misakanet_submit_intake 无凭据提交脱敏失败报告。
- 维护跨环境基础设施（WSL、NTFS、FANUC 机器人等）的工程师，查阅 devops / fanuc 等领域课程快速定位环境特定的坑。
- 研究 Agent 学习与知识复用的评估者，运行 scripts/retrieval_noisebench.py 等基准对比课程注入对模型命中率的提升。
- Python/数据分析脚本作者通过 pip install misakanet-core，在 notebook 中用 search_lessons() 函数检索修复方案。
这个 Agent 有哪些优点和局限？
- 零依赖架构：核心引擎仅用 Python 标准库实现 BM25，无向量数据库、无嵌入模型、无自建服务器，git clone 即可本地无限量检索。
- 双接入面设计：本地 stdio MCP 与远程 HTTP MCP（Cloudflare Worker + D1）共享同一知识核心，远程匿名即可搜索，本地注册后不限量。
- 课程有证据分级（E0 社区报告到 E4 生产验证），且 PR 需通过 50 个 CI 工作流门禁，内容可信度可审计。
- 无账号 intake 闭环：Agent 可通过 misakanet_submit_intake 无 Bearer token 提交脱敏故障报告，经人工评审转为课程，未解决的故障还会进入公开需求看板。
- 周度基准测试数据公开（Cloudflare Workers AI），量化证明课程上下文对小模型有 2 倍、对大模型有 +31% 的命中率提升。
- 检索仅支持 BM25 关键词匹配，无语义/向量检索；若查询措辞与课程关键词不匹配可能漏检（可选 pip install misakanet[semantic] 提供语义扩展）。
如何安装或部署这个 Agent？
方式一（远程，零安装）：无需任何安装，Agent 能发 HTTP 请求即可 curl 调用 https://misakanet.org/mcp。方式二（本地 MCP）：git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet，需要 Python 3.10+，然后 python3 scripts/mcp_server.py，并在 MCP 客户端配置中注册该服务器。方式三（CLI）：pip install misakanet 后直接运行 misakanet "database is locked"。方式四（Python 库）：pip install misakanet-core。方式五（DSH 插件）：dsh plugin add misakanet。远程 HTTP MCP 匿名限 5 次读取/天/IP，可通过 misakanet_register 工具获取 node_id + token 解除限制；本地 stdio MCP 不限量。
如何使用这个 Agent？
本地搜索：python3 search_knowledge.py "pip install timeout"。远程 MCP 搜索（无账号）：curl -sS https://misakanet.org/mcp -H "Content-Type: application/" -H "MCP-Protocol-Version: 2025-06-18" -d '{"rpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_submit_intake","arguments":{"problem":"YOUR PROBLEM","source":"your-agent"}}}'（搜索同理，将工具名换为 misakanet_search）。接入 Claude Code：claude mcp add --transport http misakanet <远程或本地端点>。Python 库调用：from misakanet.search import search_lessons; results = search_lessons("pip install timeout")。通过 Glama 网关接入：在 glama.ai 的 MisakaNet connector 页面点击 Connect，将生成的网关 URL 作为远程 MCP 服务器加入 Cursor / VS Code / ChatGPT 桌面版。提交失败报告时使用 kind="missing_lesson"，提问用 kind="question"；切勿发送密钥或原始私有日志。
这个 Agent 与同类方案有什么区别？
README 中列出了同类失败/经验知识 MCP 项目的对比：deadends.dev（同样存失败→解法，但 MisakaNet 增加 DCO 审校、证据分级与零依赖本地检索）、Prior（偏已验证方案交换，非失败记忆专库）、Kira（会话/项目级 Scars 警告，MisakaNet 为跨项目公开可审计课程库）、Casebook-MCP（同为故障复盘库，MisakaNet 带 intake 闭环与证据分级）、knownissue（issue 工单闭环 vs 审校课程检索）、fix-memory-mcp（本地私有 vs 公开共享）、cogmem（通用记忆层 vs 失败知识专库）。MisakaNet 的差异化优势：Git 版本化、零依赖、失败恢复专用、默认公开可审计。