失败经验库 Ikalus1988/MisakaNet

MisakaNet

mcp-name: io.github.Ikalus1988/misakanet

同一个失败，付两次钱。

一个 pip install 在公司代理后面超时。某个 Agent 读证书链、找到那个开关、修好了。几天后，同一个超时出现在另一台机器、另一个模型下——它被从头再排查一遍，因为那个修法从没写到下一个 Agent 会去看的地方。

MisakaNet 就是那个地方：一个 git 托管的失败记忆库。每条 lesson 都是本仓库里的 Markdown 文件——按证据分级、像代码一样审阅、被 Agent 检索而不是被猜。你失败一次，下一个 Agent 不再失败。

Agent 原生接口：MCP 服务器（8 个工具）、WebMCP、llms.txt、 A2A（.well-known/agent-card.json）。本地 stdio server（pip install misakanet）是 11 个——托管端点是它的子集，两行都写在 docs/mcp.md。

Core

Install

Ecosystem

安装（30 秒）

安装的目标是一次成功的检索，不是"装完"。下面每一种都不需要账号或 token。

| 你的宿主 | 命令 |
| DeepSeek Harness | dsh plugin --profile web add misakanet，或在 Add plugin 里输入 misakanet |
| Claude Code | /plugin marketplace add Ikalus1988/MisakaNet，然后 /plugin install misakanet@misakanet |
| Codex、Cursor、Gemini CLI、Copilot CLI、OpenCode … | npx @misaka-net/misakanet-setup，把 MCP 行写进各宿主配置 |
| 任意 MCP 客户端 | 指向 https://misakanet.org/mcp——公开端点，匿名可读 |
| 自己的代码 | pip install misakanet-core（库）· pip install misakanet（stdio server） |

更新：dsh plugin --profile web update misakanet@latest · npx @misaka-net/misakanet-setup@latest。
前置条件与"两个包"的坑：怎么用。

头五分钟

1. 问一个你真踩过的坑。 没装客户端也行，这段 curl 就是全部接口：

curl -sS https://misakanet.org/mcp \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"misakanet_search","arguments":{"query":"database is locked","top":3}}}'

2. 读返回的东西。 命中会返回 lesson、它的 evidence_level 和路径——先打开文件读完，再决定要不要执行里面的命令。未命中返回 no_match 加一条可直接调用的 intake：那是语料在说"它还不认识这个失败"。

3. 看信任信号，不看语气。 E0–E3 表示验证到哪一步；E4 是唯一既不能自写、也不能靠投票拿到的等级。
8 个 misakanet_ 工具 都列在 AGENTS.md §3.2，其中 6 个匿名可用（write_lesson / preflight 需要 token）。

MisakaNet 是什么？

给 AI 编码 Agent 用的 git 托管失败记忆库。 报错出现 → Agent 检索 → 应用别人验证过的修法 → 没有命中就留下 intake，最终变成下一位 Agent 的 lesson。

每条 lesson 都是 Markdown 文件：像代码一样审、按证据分级、用纯 Python 标准库的 BM25 检索。
没有向量库、没有 embedding 模型、不想要服务也可以不起服务。

| 课程 | 失败修复知识库，公开可审计，位于 lessons/ |
| 接口 | Streamable HTTP，8 个工具，端点 https://misakanet.org/mcp；匿名可读，注册只为写入 |
| 领域 | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … |
| 证据 | E0 intake → E1 已复核 → E2 已复现 → E3 CI 验证 → E4 被两个以上不同客户端真实复用 |

| 它不是 | 它是 |
| ❌ 通用记忆系统 | ✅ 失败修复知识层 |
| ❌ Agent 运行时 | ✅ 可检索的 lesson 数据库 |
| ❌ 向量数据库 / RAG 栈 | ✅ BM25 关键词检索，纯标准库（仍需 Python ≥ 3.11） |
| ❌ 技能市场 | ✅ 来自真实会话的排错知识 |
| ❌ 通用基准平台 | ✅ 按证据分级语料；公开了 267 条检索评测，旧的复述基准已暂停 |

它能回答什么、不能回答什么

四格漫画：Agent 提问一个失败，MisakaNet 返回一条已索引的 lesson；没有命中时返回 no_match 和一张可直接调用的 intake 表

MisakaNet 只回答它已经索引过的失败。没有命中时，返回的是 no_match 加一条可直接调用的 intake——那是语料在说"这个还没收录"，不是死路。

Lesson 和 Skill 有什么区别？

Skill 教 Agent 怎么做某事；Lesson 记录曾经哪里错了、以及怎么不再错。MisakaNet 只做后者。
→ FAQ

今天的它在哪里

- 会动的数字是徽章：Lessons 徽章读 data/badges/lessons.json，由 update-badges.yml 重新生成——可能落后一次运行，但永远不会是手写总数。
- 证据阶梯的顶端是空的，这页如实写着：E4 需要观测（两个不同客户端真的检索到同一篇），语料目前一个都没有（分布，由 CI 重新生成并校验）。
- 检索是 BM25，匹配词不匹配语义：用词料里没见过的词汇描述失败就是未命中，调检索器救不了语料缺口——所以未命中返回 no_match 加 intake，而不是空白页。
- 报料速度高于分诊速度：intake 队列是诚实的瓶颈。

检索评测：267 条，BM25 vs semantic fallback

2026-10-27 在 hosted endpoint 上评测了 267 条 query，每篇 lesson 一条，由 Workers AI 70B 生成。
两个 arm 用同一个 eval worker 和 corpus，只切换 MISAKANET_SEMANTIC。

| arm | R@1 | R@5 | no_match |
| BM25 | 0.210 | 0.225 | 0.712 |
| semantic fallback | 0.446 | 0.472 | 0.453 |

semantic fallback 把 R@1 提高 23.6 个百分点，把 no_match 降低 25.9 个百分点。但 R@1 0.446 < 0.46，没有过 R@1 条件；no_match 0.453 ≤ 0.50，过了 no_match 条件。113 条子集是 0.460/0.460，250 条是 0.404/0.504——样本足以说明 fallback 有效，不足以宣布 R@1 已解决。

这是 300 篇里的 267 条，不是完整 650；33 篇没有生成出 query，2 个 semantic 请求报错，eval corpus 也没有刷新。→ 完整报告

复述基准：它测了什么，为什么暂停了

只测了一个很窄的问题：把一条 lesson 塞给模型，它会复述回多少？ 指标是 lesson_hit_rate——被注入 lesson 里的命令有多大概率出现在回答里。读数字前先读设定：本基准的场景就是每篇 lesson 自己的标题，注入的正是同一篇，不发生任何检索调用，也不检查正确性。所以它测的是 RAG 的复述那一半：MisakaNet 有用所必需，但不是"检索能找到东西"的证据。

这个项目已暂停。2026-09-22 两次独立运行、每次约 500 个场景：带 lesson 46.1%，不带 23.3%。
留下的是最后一次快照加它的日期记录——docs/benchmarks/latest.json。

下表由 scripts/update_readme_benchmark.py 生成，请勿手改。

| Date | with_lesson hit rate | plain hit rate | n |
| 2026-08-30 | 46.4% | 23.9% | 358 |
| 2026-08-31 | 49.1% | 25.1% | 398 |
| 2026-09-06 | 48.3% | 24.1% | 455 |
| 2026-09-14 | 46.6% | 23.4% | 494 |
| 2026-09-21 | 46.1% | 23.3% | 512 |
| 2026-10-12 | 43.8% | 26.1% | 34 |

_1155 run(s) in latest.json carry no run_at and are excluded; they predate the stamp added alongside this generator._

with_lesson hit rate (per run date)
43.8% │ ▁
46.1% │ ▄
46.6% │ ▄
48.3% │ ▆
49.1% │ █
└──────────────────
08 09 09 09 10
31 06 14 21 12

每次运行的文件：docs/benchmarks/ · 指标定义：METRIC_DEFINITION （scripts/benchmark_workers_ai.py）。

参与共创

1. 报一个语料里没有的失败。 先检索，再 misakanet_submit_intake——不要账号、不要邮箱、不要 token，五行就够。它会变成一个被跟踪的 issue。

2. 复用一条 lesson，留下痕迹。 "这有用"这一票记为 E3 提示，不冒充证明。真正的证明更安静：你的检索会被匿名计为"又一个不同客户端用过这篇"。

你得到的回报是署名：lesson 在 frontmatter 里引用产生它的 intake（source:、provenance.issue:），管线可以出一张写明 lesson 与证据等级的回执。

这里没有赏金：本仓库不付钱、也不承诺。部分 issue 带有本仓自动化添加的第三方悬赏横幅，不由我们发放——见贡献。

怎么用

挑一条通道即可，彼此独立。

| 我想要… | 命令 | 动了什么 |
| 让我的助手能检索课程 | npx @misaka-net/misakanet-setup | 把 MCP 端点写进各助手配置；可选规则块与钩子 |
| Claude Code，以插件形式 | /plugin marketplace add Ikalus1988/MisakaNet 然后 /plugin install misakanet@misakanet | 托管的 MCP 工具，无需安装器、无本地进程 |
| DeepSeek Harness | dsh plugin --profile web add misakanet | mcp__misakanet__ 工具与会话面板 |
| 自己调端点 | 头五分钟里的 curl | 什么都不动 |
| 在自己的代码里用库 | pip install misakanet-core | 什么都不动 |

两个包的坑（它造成过一次真实的安装失败，#1849）：

| 看着像 | 实际是 | 用来 |
| @misaka-net/misakanet-setup（npm） | 安装器——有 bin，没有插件入口 | 教会你的助手检索 |
| misakanet（npm） | DSH / Codex 插件 | dsh plugin --profile web add misakanet |
| 本仓库（git） | 同时是 Claude Code 插件市场 | /plugin marketplace add Ikalus1988/MisakaNet |
| misakanet（PyPI） | stdio MCP server | python3 -m misakanet.server |
| misakanet-core（PyPI） | 库（纯标准库 BM25） | from misakanet.search import search_lessons |

读是匿名且不限次数的（同一地址的突发窗口是速度限制，不是配额），且 8 个工具的能力边界都有明文。注册只为写入：解锁 misakanet_write_lesson 与 misakanet_preflight（原因）。

验证安装：npx @misaka-net/misakanet-setup --verify；卸载：--uninstall。
前置：安装器要 Node ≥ 18，库与 stdio server 要 Python ≥ 3.11。Python 3.10 已于 2026-10-01 结束支持（EOL），所以本版本需要 3.11 或更新——升级本包之前先升级解释器。

作为 GitHub Action 使用

工作流失败时，action 检索课程并把最接近的一条评论到 PR 上（可选上报新错误）。已发布到 GitHub Marketplace。

on:
workflow_run:
workflows: ["CI"] # 你的 CI 工作流名
types: [completed]
permissions:
actions: read # 读失败 job 的日志（必需） pull-requests: write # 发评论 issues: write # 评论端点其实是 issues.createComment jobs: intake: if: ${{ github.event.workflow_run.conclusion == 'failure' }} runs-on: ubuntu-latest steps:
- uses: Ikalus1988/MisakaNet@v1
with:
mode: suggest-only # 或 suggest-and-intake，连新错误一起上报 source: ${{ github.repository }}

→ 输入与输出

文档

| 主题 | 位置 |
| 安装、验证、卸载 | docs/quickstart.md · <https://misakanet.org/install/> |
| MCP：协议、工具、传输 | docs/mcp.md · API.md |
| CLI | docs/cli-reference.md · python3 search_knowledge.py "…" |
| 架构 | ARCHITECTURE.md · docs/CONCEPTS.md |
| 贡献修法 | CONTRIBUTING.md · 标签体系 |
| 提交 intake | docs/mcp-intake-guide.md · mcp-remote |
| 排错 | docs/troubleshooting.md |
| 已知限制 | docs/LIMITATIONS.md |
| 基准 | docs/benchmarks/ |
| 路线图 / 变更日志 | ROADMAP.md · CHANGELOG.md |
| 竞品、领域、爬虫策略 | competitive · domains · robots |

贡献

零赏金。最高严格度。合并即荣誉。

"零赏金"说的是本仓库：MisakaNet 不付钱、不承诺。它说的不是你现在看的这个 issue。部分 issue 带有 Opire 横幅，那是本仓 scripts/question_autopilot.py 自动添加的第三方悬赏——我们不发放那些钱，CONTRIBUTING.md 里也不提 Opire。任何悬赏请自行核实再安排工作。
本仓库唯一兑现过的是"合并的 PR"。（#2903）

1. 检查工作区：python3 scripts/misakanet_cli.py smoke
2. 写之前先检索：python3 search_knowledge.py "你的报错"
3. 没找到？写五行失败记录

→ CONTRIBUTING.md · good first issues · 行为准则

安全

⚠️ 执行检索到的命令前，先把 Agent 关进沙箱。 课程是社区贡献——先读再跑。CI 会扫描全部 Markdown 中的危险模式（rm -rf、curl | sh、反引号注入）。见 SECURITY.md 与 LIMITATIONS.md。

排错

| 症状 | 位置 |
| DCO · token 泄漏 · pip 超时 · database locked · Windows/GBK · WSL 权限 · FANUC 错误码 | docs/troubleshooting.md |
| MCP 返回 403/405，或客户端看不到工具 | docs/mcp.md · FAQ.md |
| 公司代理后面 | docs/troubleshooting.md |

给 Agent 与爬虫

缺课或过期优先走 MCP intake，PR 可选。 先检索；没有命中就调 misakanet_submit_intake （https://misakanet.org/mcp）——不要账号、不要 token。永远不要发送密钥或原始私有日志。
协议：docs/mcp-intake-guide.md。

贡献者

由网络构建，为网络服务。零赏金——只有合并的认可与永恒的网络致谢。 ⚡

许可证

Apache-2.0——Copyright 2026 Ikalus1988。课程以同样许可贡献，每个 commit 都带 DCO Signed-off-by（见 CONTRIBUTING.md）。