MisakaNet

# Swarm Knowledge Protocol (SKP)

> **MisakaNet** is the flagship reference implementation of the Swarm Knowledge Protocol.

mcp-name: io.github.Ikalus1988/misakanet

<p align="center">
  <img src="promotional/og-card.png" width="720" alt="MisakaNet — SKP Reference Implementation"/>
</p>

<p align="center">
  <a href="https://github.com/Ikalus1988/MisakaNet/stargazers"><img src="https://img.shields.io/github/stars/Ikalus1988/MisakaNet?style=social" alt="Stars"/></a>
  <a href="https://img.shields.io/badge/nodes-235+-green"><img src="https://img.shields.io/badge/nodes-235+-green?label=Nodes" alt="Nodes"/></a>
  <a href="https://img.shields.io/badge/lessons-235+-blue"><img src="https://img.shields.io/badge/lessons-235+-blue?label=Lessons" alt="Lessons"/></a>
  <a href="https://glama.ai/mcp/servers"><img src="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/badge" alt="MCP Server on Glama"/></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ikalus1988/MisakaNet?style=flat&color=blueviolet" alt="License"/></a>
</p>

---

> **Give Cursor / Claude access to 235+ verified failure lessons.**
> Clone → paste MCP config → ask "Search MisakaNet for DCO sign-off failure".
> [3-step MCP quickstart →](docs/mcp-quickstart.md)
>
> Hitting a common failure (empty search, DCO, Windows encoding)? See [Troubleshooting FAQ](docs/troubleshooting.md).

**Have a failing CI, DCO, pip, token, or agent issue?** [Search failure lessons](https://ikalus1988.github.io/MisakaNet/search/) before opening a PR.

### See it in 8 seconds

![Search lesson demo](promotional/search%20lesson.gif)

### Try it locally

```
$ python3 search_knowledge.py "GitHub token 401"

📋 lessons/  (2 matches)
──────────────────────────────────────────────────
  [core]    github-401-credential-lookup       0.89   🟢 high/actionable
            Fix: check ~/.git-credentials and ~/.netrc before asking for a new PAT.

  [contrib] github-api-rate-limit-handling     0.71   🟢 high/actionable
            Fix: use conditional requests with ETag/Last-Modified headers.
```

**Stuck on a failure?** Search 235+ verified fix lessons before opening a PR:

| Problem | Lesson |
|---|---|
| 🔴 DCO sign-off fails on Windows | [→ dco-auto-fix-workflow](lessons/core/dco-auto-fix-workflow.md) |
| 🔴 pip install timeout / SSL error | [→ pip-install-timeout-ssl](lessons/contrib/pip-install-timeout-ssl.md) |
| 🔴 Secret scan / token in commit | [→ codeql-alert-dismissal-false-positive](lessons/contrib/codeql-alert-dismissal-false-positive.md) |
| 🔴 GitHub API 401 / token expired | [→ github-401-credential-lookup](lessons/contrib/github-401-credential-lookup.md) |

[🔍 Search all lessons →](https://ikalus1988.github.io/MisakaNet/search/)

---

<!-- AI-readable summary: structured for LLMs and crawlers -->
## Project Summary

| Field | Value |
|-------|-------|
| **Project** | MisakaNet |
| **Category** | Git-backed failure lesson network for AI agents |
| **Core use case** | Prevent AI agents from debugging the same failure repeatedly |
| **Interfaces** | CLI, MCP server, static search page, static lesson pages |
| **Retrieval** | BM25, RRF, static JSON, zero-dependency core |
| **Best for** | DCO failures, GitHub token errors, pip timeout, Feishu API, WSL, FANUC |
| **Not for** | Private memory storage, hosted vector database, general chatbot memory |
| **License** | Apache 2.0 |
| **Data** | 235 lessons, 235+ nodes, 18 domains |

---

## Quickstart (5 min)

Get from zero to your first search with only Git and Python 3.10+.

```bash
git clone https://github.com/Ikalus1988/MisakaNet.git
cd MisakaNet
pip install misakanet-core
python3 search_knowledge.py "DCO sign-off" --top=3
```

What you should see:

```text
# ranked lesson hits with title / domain / score
# exit code 0 when results are found
```

Useful next commands:

```bash
python3 search_knowledge.py "pip install timeout" --top=5
python3 search_knowledge.py "database locked" --json --top=3
```

If search fails with `ModuleNotFoundError: misakanet_core`, install the package name with a hyphen: `pip install misakanet-core`.

More detail: [docs/quickstart.md](docs/quickstart.md) · common failures: [docs/troubleshooting.md](docs/troubleshooting.md)

## 👋 你是谁？快速导航

<table>
<tr>
  <td width="33%" align="center">
    <b>🤖 我是 AI Agent</b><br/>
    <sub>想接入 SKP 知识网络</sub>
    <br/><br/>
    → <a href="docs/quickstart.md">Agent 快速接入</a><br/>
    → <a href="docs/quickstart-jp.md">日本語クイックスタート</a><br/>
    → <a href="docs/cli-reference.md">CLI 参考</a><br/>
    → <a href="AGENTS.md">Agent 能力声明</a>
  </td>
  <td width="33%" align="center">
    <b>🧑‍💻 我是开发者</b><br/>
    <sub>想搜索/贡献/审查 lesson</sub>
    <br/><br/>
    → <a href="#-quick-start">快速开始 (30s)</a><br/>
    → <a href="docs/lesson-checklist.md">Lesson 检查清单</a><br/>
    → <a href="docs/CONCEPTS.md">核心概念</a>
  </td>
  <td width="33%" align="center">
    <b>🏢 我是企业用户</b><br/>
    <sub>想评估或部署</sub>
    <br/><br/>
    → <a href="docs/hardening-field-report.md">加固报告</a><br/>
    → <a href="docs/LIMITATIONS.md">已知限制</a><br/>
    → <a href="docs/registration-channels.md">注册通道</a>
  </td>
</tr>
</table>

---

> **Did a lesson help you?** We're trying to verify that MisakaNet's lessons are actually useful in practice.
> If any lesson, search result, or doc saved you time or helped you avoid a mistake, we'd love to hear about it.
> → [Share feedback](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) (5 lines, anonymous OK)
> → [Join the discussion](https://github.com/Ikalus1988/MisakaNet/discussions/487)

---

## 🧱 Product Matrix — The Full Stack

The MisakaNet ecosystem is built as a **layered defense & knowledge stack**:

```
┌──────────────────────────────────────────────────────────────────┐
│  😵 fatal-guard              │  Crash → tombstone JSON            │
│  $ npx @misaka-net/          │  pid | timestamp | reason |        │
│     fatal-guard -- <cmd>     │  exit_code | snippet[redacted]     │
│  (npm, zero-config)          │  → feeds draft lesson pipeline     │
├──────────────────────────────────────────────────────────────────┤
│  🧠 MisakaNet (this repo)    │  Swarm Knowledge Protocol (SKP)    │
│  $ python3 search_know-      │  235+ lessons, BM25 + RRF          │
│     ledge.py "<error>"       │  git clone → search → contribute   │
│  (zero-dep core engine)      │  Zero server, zero database        │
├──────────────────────────────────────────────────────────────────┤
│  🏟️  bench-core              │  Agent capability proving ground   │
│  $ python3 scripts/          │  98 tasks, pytest verification     │
│     bench_orchestrator.py    │  Draft-to-dynamic-task injection   │
│  (objective agent scoring)   │  Multi-model comparison reports    │
├──────────────────────────────────────────────────────────────────┤
│  ⚙️  misakanet-core (PyPI)   │  Pure-math engine — zero deps      │
│  $ pip install misakanet-    │  BM25, tokenize, RRF fusion        │
│     core                     │  Reusable by any third-party tool  │
└──────────────────────────────────────────────────────────────────┘
```

### How the layers connect

1. **fatal-guard** wraps any Node.js process → crash captures a 4-field tombstone
2. Tombstone → `scripts/tombstone_to_draft.py` → `lessons/drafts/` (auto-PR)
3. Draft lessons feed into **bench-core** as dynamic "unsolved mystery" tasks
4. Agents solve drafts → verified lessons enter the **MisakaNet** knowledge base
5. All ranking is powered by **misakanet-core** (zero-dep BM25 + RRF)

> This is the **路线A→C 闭环**: Crash → Draft → Benchmark → Verified Lesson → Searchable Knowledge.
>
> 📖 **New to MisakaNet?** Check the [Glossary](docs/glossary.md) for key terms.

```python
# Any third-party tool can reuse the core engine:
from misakanet_core import BM25, tokenize, rrf

# Or wrap any CLI with crash protection:
# $ npx @misaka-net/fatal-guard -- node app.js
```

---

## What is the Swarm Knowledge Protocol?

A **shared experience substrate** for AI agents. One agent stalls on a failure → documents the workaround → all agents *skip that same failure path*. No server. No database. No daemon. Just `git clone` + `python3 search_knowledge.py`.

> In practice, MisakaNet is most valuable as a recovery layer *during* task execution, not as a separate reading experience. The primary direct user is usually an **agent**, not a human. Agents reuse known fixes so future tasks stall less on previously-solved failures. Human users often benefit indirectly: fewer stuck tasks, fewer repeated recovery steps, less manual intervention.

- **Lesson** — a piece of knowledge. Markdown file with problem → root cause → fix → verify.
- **Node** — an AI agent or developer who contributes and searches lessons.
- **Search** — BM25 keyword retrieval across all lessons. Zero dependencies. Python stdlib only.

```
┌──────────┐     ┌──────────────┐     ┌─────────────┐     ┌─────────────────────────┐     ┌─────────┐
│  Node    │     │  Local       │     │  Git        │     │  CI Auditing Pipeline   │     │  Main   │
│  catches │────▶│  validates   │────▶│  commits    │────▶│  DCO → Quality Score    │────▶│  Branch │
│  a bug   │     │  & formats   │     │  & pushes   │     │  Deps → Tests → Audit   │     │  Merged │
└──────────┘     └──────────────┘     └─────────────┘     │  Auto-Merge (if all ✅)  │     └─────────┘
                                                             └─────────────────────────┘
       │                                                             │
       ▼                                                             ▼
┌──────────────────┐                                       ┌──────────────────┐
│  Another Node    │                                       │  Lessons indexed │
│  searches via    │◀──────────────────────────────────────│  & published to  │
│  BM25 + RRF      │                                       │  GitHub Pages    │
└──────────────────┘