misakanet

MisakaNet

mcp-name: io.github.Ikalus1988/misakanet

同一个故障，付了两次代价。

在企业代理后运行 pip install 超时了。某个 Agent 找到了修复方法。几天后，另一台机器、另一个模型再次遇到同样的 超时——由于修复方法从未记录在下一个 Agent 会查找的地方，只能从头开始排查。

MisakaNet 就是这样一个地方：由 git 支持的故障记忆库。每条经验都是此 仓库中的一个 Markdown 文件——根据证据评定等级，像代码一样审查，由 Agent 检索，而非靠猜测。 你只需失败一次；下一个 Agent 就不会再失败。

面向 Agent 的原生接口：MCP 服务（8 个工具）、WebMCP、llms.txt， 通过 .well-known/agent-card.json 进行 A2A 发现。

核心   

安装   

生态系统   

---

安装（30 秒）

安装的目的不是完成安装，而是进行首次成功搜索。以下方式都不需要账号或令牌。

你的宿主	命令
DeepSeek Harness	dsh plugin --profile web add misakanet — 或在添加插件中输入 misakanet
Claude Code	/plugin marketplace add Ikalus1988/MisakaNet 然后 /plugin install misakanet@misakanet
由安装程序管理	Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro · MiniMax Code
其他 MCP 客户端	将其指向 https://misakanet.org/mcp — 公共端点，匿名读取
你自己的代码	pip install misakanet-core（库）· pip install misakanet（stdio 服务）

由安装程序管理的这一行，就是 npx @misaka-net/misakanet-setup 写入各宿主配置的内容。

更新：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. 阅读返回的内容。 命中时会返回经验、其 evidence_level 和路径——打开文件，先阅读修复方法，再运行其中的任何命令。未命中时会返回 no_match 和可直接调用的收集表单：知识库表示它目前还不知道这个问题。

3. 查看可信度信号，而不是措辞。 E0–E3 表示经验经过了何种程度的验证；E4 则是任何人都无法撰写或投票获得的等级。

什么是 MisakaNet？

面向 AI 编码 Agent、基于 Git 的故障记忆库。 出现错误 → Agent 进行搜索 → 应用他人已验证的修复方法 → 如果没有匹配项，未命中结果就会成为收集条目，而收集条目会成为供下一个 Agent 使用的经验。

每条经验都是一个 Markdown 文件：像代码一样接受审查，按证据评级，并使用 Python 标准库中的 BM25 进行检索。托管的 MCP 端点只会在 BM25 未返回匹配项时，可选地使用语义回退（bge-m3 + Vectorize）；MISAKANET_SEMANTIC=0 可将其禁用。本地无需向量数据库；除非你想要，否则也无需服务器。

经验	故障恢复知识库，开放且可在 lessons/ 中审计
领域	rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows …
证据等级	E0 收集 → E1 已审查 → E2 已复现 → E3 已通过 CI 验证 → E4 已观察到被两个或更多不同客户端重复使用

它不是	它是
❌ 通用记忆系统	✅ 故障恢复知识层
❌ Agent 运行时	✅ 可搜索的经验数据库
❌ 必需的向量数据库 / RAG 技术栈	✅ 优先使用 BM25；托管端点提供可选且可禁用的语义回退
❌ 技能市场	✅ 来自真实会话的调试知识
❌ 通用基准测试平台	✅ 按证据评级的知识库；已发布一轮包含 267 个查询的检索测试，旧版复述基准测试已暂停

它能回答什么——以及不能回答什么

MisakaNet 只回答已编入索引的故障问题。当没有匹配项时，回复会包含 no_match 和可直接调用的 intake——这表示知识库在说“目前还没有这个问题”，而不是无路可走。

经验与技能

技能教 Agent 如何做某件事；经验记录此前发生了什么问题，以及如何避免再次失败。MisakaNet 只属于后者。→ 常见问题

当前情况

• 会变化的数字是徽章，这是有意为之：Lessons 徽章会渲染 data/badges/lessons.json，该文件由 update-badges.yml 重新生成，因此可能滞后于某次运行，但绝不会 手动填写总数。
• 证据阶梯的顶端目前是空的，本页对此如实说明。 E4 需要一项观察——两个不同的客户端实际检索到一条课程——而语料库中目前还没有 (分发，由 CI 重新生成并检查）。
• 搜索优先使用 BM25；托管端点可以回退到嵌入。 本地／离线模式仍使用标准库 BM25；仅当 BM25 没有匹配结果时才会运行回退，设置 MISAKANET_SEMANTIC=0 可将其 关闭。语料库缺口仍会导致未命中：回复会是 no_match 加上一条提交记录，而不是空页面。
• 收到缺口报告的速度快于分流处理的速度。 提交队列是实际的瓶颈。
• 语料库可供下载和引用。 data.misakanet.org 发布带版本号的 数据包——完整语料库、基准测试查询集和每次运行的所有产物——并为每个文件提供 SHA-256 校验值和明确的文件许可协议（DATASET.md）。计数 保存在每个版本的 manifest.json 中，而不是正文里。

检索基准测试：267 个查询，BM25 与语义回退

2026-10-27，使用 Workers AI 70B 生成的 267 个查询（每条课程一个），对托管端点的检索路径进行了评估。两组使用相同的评估 Worker 和语料库；唯一变化的是 MISAKANET_SEMANTIC。

组别	R@1	R@5	no_match
BM25	0.210	0.225	0.712
语义回退	0.446	0.472	0.453

回退使 R@1 提高了 23.6 个百分点，并使 no_match 降低了 25.9 个百分点。它尚未 达到目标中关于 R@1 的要求（0.446 < 0.46）；no_match 则在目标范围内 （0.453 ≤ 0.50）。一个包含 113 个查询的子集达到 0.460/0.460，而包含 250 个查询的子集达到 0.404/0.504：样本量 足以表明回退有效，但不足以认定 R@1 问题已解决。

这是从 300 条目池中抽取的 267 个查询，并非全部 650 条；有 33 个池条目未生成查询，2 个语义请求 出错，评估语料库也未刷新。→ 完整报告

复述基准测试：测量内容及暂停原因

一个范围有限的问题：把一条课程交给模型后，它能复述多少内容？ 指标为 lesson_hit_rate——答案中复现的注入课程命令所占的比例。 先了解设置，再看数字：此基准测试中的场景是每条课程自己的标题，注入的 课程就是该课程本身， 不会进行检索调用，也不检查正确性。它测量的是 RAG 中的复述部分： 这是 MisakaNet 发挥作用的必要条件，但不能证明搜索能找到任何内容。

这项运行已暂停。2026-09-22 进行了两次独立运行，每次约有 500 个场景：粘贴课程时为 46.1%，不粘贴时为 23.3%。目前留下的内容是最后一次快照及其带日期的记录 — docs/benchmarks/latest.json。

下表由 scripts/update_readme_benchmark.py 生成； 请勿手动编辑。

日期	with_lesson 命中率	plain 命中率	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

latest.json 中有 1155 次运行没有 run_at，因此未纳入统计；这些记录早于本生成器推出时添加的时间戳。_

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/ · 指标定义：scripts/benchmark_workers_ai.py 中的 METRIC_DEFINITION。

参与其中

1. 报告知识库中尚未收录的故障。 先搜索，然后调用 misakanet_submit_intake — 无需账户、邮箱或令牌，写一份五行报告就够了。它会成为一个可追踪的问题。

2. 复用经验，并留下痕迹。 “这有帮助”投票会被记录为 E3 提示，而非 证明。真正的证明更悄然：你的检索会被匿名计数，成为又一个独立客户端。

你会得到什么：归因信息。 一条经验会注明产生它的 intake（source:、 provenance.issue:），而流水线可以生成一份回执，列出经验及其证据级别。

这里没有赏金：本仓库不支付报酬，也不作任何承诺。有些问题带有第三方奖励横幅，这是我们自己的自动化添加的；奖励不由我们管理 — 请参阅 贡献指南。

如何使用

npx @misaka-net/misakanet-setup 会将 MisakaNet 安装到助手自己的配置中 — 所有客户端都使用同一条 命令。十个受支持的客户端及其对应功能，请见 安装页面。使用 npx @misaka-net/misakanet-setup --verify 验证安装；使用 --uninstall 卸载。 读取匿名且不限量；注册仅用于写入（原因）。 安装程序需要 Node ≥ 18，库和 stdio 服务端需要 Python ≥ 3.11。Python 3.10 已于 2026-10-01 结束生命周期，因此此版本需要 3.11 或更新版本 — 升级软件包前，请先升级解释器。

其他接入渠道

• 将 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 服务 — python3 -m misakanet.server。
• misakanet-core（PyPI）是库（仅使用标准库的 BM25；托管端点的语义回退在服务端运行）— from misakanet.search import search_lessons。

将其用作 GitHub Action

工作流失败时，该 Action 会搜索经验，并在拉取请求中评论最接近的匹配项（还可选择报告新的错误）。 已发布到 GitHub Marketplace。

on:
  workflow_run:
    workflows: ["CI"]                # your CI workflow's name
    types: [completed]
permissions:
  actions: read                      # read the failing job's log (required)
  pull-requests: write               # post the comment
  issues: write                      # the comment endpoint is issues.createComment
jobs:
  intake:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    steps:
      - uses: Ikalus1988/MisakaNet@v1
        with:
          mode: suggest-only         # or suggest-and-intake, to report new errors too
          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/
数据集（语料库 + 查询集，可下载）	DATASET.md · https://data.misakanet.org/latest.json
路线图 / 更新日志	ROADMAP.md · CHANGELOG.md
竞品、域名、爬虫政策	竞争分析 · 域名 · robots

贡献

零悬赏，严谨至上。合并即可获得认可。

“零悬赏”指的是本仓库：MisakaNet 不支付任何费用，也不作任何承诺。这并不是在说你正在查看的问题。部分问题带有 Opire 横幅，用于宣传第三方奖励；这是我们自己的 scripts/question_autopilot.py 自动添加的——这些奖励并非由我们管理，而且 CONTRIBUTING.md 中没有提及 Opire。请独立核实任何奖励承诺，再决定是否围绕它安排工作。本仓库唯一兑现过的承诺，就是合并 PR。 (#2903)

1. 检查检出内容：python3 scripts/misakanet_cli.py smoke
2. 动笔前先搜索：python3 search_knowledge.py "your error here"
3. 没有找到？分享你的失败经验——写五行就够了

本月适合新手的优先问题（10 月 26 日 – 11 月 26 日）：提交一个真实的失败案例——无需编写代码；MCP intake 无需账号；我们会协助整理格式。

→ CONTRIBUTING.md · 适合新手的问题 · 行为准则

安全

⚠️ **执行检索到的命令前，请先在沙箱中运行 Agent。**经验教训由社区贡献——运行前请先审查。CI 会扫描所有 Markdown 中的危险模式（rm -rf、curl | sh、反引号注入）。请参阅 SECURITY.md 和 LIMITATIONS.md。

故障排查

症状	位置
DCO · 令牌泄露 · 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 并非必需。**请先搜索；如果没有匹配项，请在 https://misakanet.org/mcp 调用 misakanet_submit_intake——无需账号，也无需令牌。切勿发送机密或未经处理的私人日志。协议说明：docs/mcp-intake-guide.md。

贡献者

由网络构建，服务于网络。不支付悬赏——只有合并批准和网络永恒的谢意。 ⚡

许可证

Apache-2.0 — 版权所有 2026 Ikalus1988。课程内容遵循相同许可证贡献，且 每次提交都附有 DCO Signed-off-by（参见 CONTRIBUTING.md）。