Metadata-Version: 2.4
Name: misakanet
Version: 2.46.0
Summary: AI Agent 分布式经验知识共享系统 — 踩坑一次，全网受益
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Ikalus1988/MisakaNet
Project-URL: Repository, https://github.com/Ikalus1988/MisakaNet
Keywords: ai-agent,knowledge-base,bm25,rag,distributed
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: misakanet-core>=2.7.0
Provides-Extra: hub
Requires-Dist: aiohttp>=3.9; extra == "hub"
Requires-Dist: websocket-client>=1.6; extra == "hub"
Requires-Dist: networkx>=3.2; extra == "hub"
Requires-Dist: PyYAML>=6.0; extra == "hub"
Requires-Dist: numpy>=1.24; extra == "hub"
Requires-Dist: keyring>=25; extra == "hub"
Provides-Extra: feishu
Requires-Dist: requests>=2.28; extra == "feishu"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2; extra == "semantic"
Provides-Extra: harvest
Requires-Dist: scrapling>=0.4.9; extra == "harvest"
Requires-Dist: scrapling[fetchers]; extra == "harvest"
Dynamic: license-file

<div align="right">

[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)

</div>

# MisakaNet

mcp-name: io.github.Ikalus1988/misakanet

> **The same failure, paid for twice.**
>
> A `pip install` times out behind a corporate proxy. An agent finds the fix. Days later the same
> timeout appears on another machine, under another model — and is debugged from scratch, because the
> fix was never written down anywhere the next agent looks.
>
> MisakaNet is that place: a git-backed **failure memory**. Every lesson is a Markdown file in this
> repository — graded by evidence, reviewed like code, retrieved by an agent instead of guessed at.
> You fail once; the next agent does not.

Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (8 tools), WebMCP, `llms.txt`,
A2A discovery via `.well-known/agent-card.json`.

<p align="center">
  <img src="promotional/misaka-compare.jpg" width="720" alt="MisakaNet — Before: 30+ min manual debugging vs After: 0.02s with MCP"/>
</p>

<p align="center">
  <em>Core</em>
  &nbsp;&nbsp;
  <a href="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-checks.yml"><img src="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-checks.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/lessons"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json" alt="Lessons"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/scripts/mcp_server.py"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/tools.json" alt="MCP Tools"></a>
  <a href="https://misakanet.org/api/search-index"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/retrieval.json" alt="Retrieval backend (today)"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blueviolet" alt="License"></a>
  <a href="https://github.com/Ikalus1988/MisakaNet/stargazers"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/stars.json" alt="Stars"></a>
</p>

<p align="center">
  <em>Install</em>
  &nbsp;&nbsp;
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python"></a>
  <a href="https://pypi.org/project/misakanet/"><img src="https://img.shields.io/pypi/v/misakanet" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/misakanet"><img src="https://img.shields.io/npm/v/misakanet" alt="npm"></a>
  <a href="https://github.com/marketplace/actions/misakanet-intake-bot"><img src="https://img.shields.io/badge/Marketplace-MisakaNet%20Intake%20Bot-blue?logo=github" alt="GitHub Marketplace"></a>
</p>

<p align="center">
  <em>Ecosystem</em>
  &nbsp;&nbsp;
  <a href="https://glama.ai/mcp/connectors/org.misakanet/misaka-net"><img src="https://glama.ai/mcp/connectors/org.misakanet/misaka-net/badges/score.svg" alt="MisakaNet MCP connector on Glama"></a>
  <a href="https://mcptoplist.com/server/io.github.Ikalus1988%2Fmisakanet"><img src="https://img.shields.io/badge/MCP-Toplist-blue" alt="MCP Toplist"></a>
</p>

---

## Install (30 seconds)

The point of an install is a first **successful search**, not the install. None of these needs an
account or a token.

| Your host | Command |
|---|---|
| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` — or type `misakanet` in **Add plugin** |
| **Claude Code** | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` |
| Installer-managed | Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro |
| **Any other MCP client** | point it at `https://misakanet.org/mcp` — public endpoint, anonymous reads |
| **Your own code** | `pip install misakanet-core` (library) · `pip install misakanet` (stdio server) |

The installer-managed row is what `npx @misaka-net/misakanet-setup` writes into each host's config.

Updates: `dsh plugin --profile web update misakanet@latest`.
Installer updates: `npx @misaka-net/misakanet-setup@latest`.
Full prerequisites and the two-package trap: [How to use it](#how-to-use-it).

## Your first five minutes

**1. Ask it something you have actually broken.** No client installed? This `curl` is the whole interface:

```bash
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. Read what came back.** A hit returns the lesson, its `evidence_level`, and its path — open the
file and read the fix before running any command in it. A miss returns `no_match` plus a ready-to-call
intake: the corpus saying it does not know this one yet.

**3. Check the trust signal, not the tone.** `E0`–`E3` say how far a lesson was verified; `E4` is the
one nobody can write or vote into.

## What is MisakaNet?

**Git-backed failure memory for AI coding agents.** An error shows up → the agent searches → it
applies a fix somebody already verified → if nothing matches, the miss becomes an intake, and the
intake becomes a lesson for the next agent.

Every lesson is a Markdown file: reviewed like code, graded by evidence, retrieved with BM25 over the
Python standard library. No vector database, no embedding model, no server unless you want one.

| | |
|---|---|
| **Lessons** | failure-recovery knowledge base, open and auditable under `lessons/` |
| **Domains** | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … |
| **Evidence** | E0 intake → E1 reviewed → E2 reproduced → E3 CI verified → **E4 observed reuse by two or more distinct clients** |

| It is not | It is |
|---|---|
| ❌ a general memory system | ✅ a failure-recovery knowledge layer |
| ❌ an agent runtime | ✅ a searchable lesson database |
| ❌ a vector database / RAG stack | ✅ BM25 keyword search, stdlib only (Python ≥ 3.10 still required) |
| ❌ a skill marketplace | ✅ debugging knowledge from real sessions |
| ❌ a retrieval benchmark | ✅ a corpus graded by evidence; the benchmark we have is paused |

### What it answers — and what it does not

![Four-panel comic: an agent asks about a failure, gets an indexed lesson back, or gets "no_match" and a ready-to-call intake form](promotional/misakanet-scope-comic.webp)

MisakaNet answers for the failures it has indexed, and only those. When nothing matches the reply is
`no_match` plus a ready-to-call `intake` — the corpus saying "not this one yet", not a dead end.

### Lesson vs Skill

A **skill** teaches an agent how to do something; a **lesson** records what went wrong before and how
not to fail again. MisakaNet is only the second thing. → [FAQ](FAQ.md)

## Where it is today

- **The numbers that move are badges**, on purpose: the Lessons badge renders
  `data/badges/lessons.json`, regenerated by `update-badges.yml`, so it can lag a run but is never a
  hand-typed total.
- **The top of the evidence ladder is empty, and this page says so.** `E4` needs an observation —
  two distinct clients actually retrieving a lesson — and the corpus has none yet
  ([distribution](docs/trust-semantics.md), regenerated and checked by CI).
- **Search is BM25, so it matches words, not meaning.** A failure described in vocabulary the corpus
  has never seen is a miss, and no retriever tuning fixes a corpus gap — which is why a miss returns
  `no_match` plus an intake instead of an empty page.
- **Reported gaps arrive faster than they are triaged.** The intake queue is the honest bottleneck.

## Benchmark: what it measured, and why it is paused

One narrow question: **when you hand a model a lesson, how much of that lesson comes back?** The
metric is `lesson_hit_rate` — the share of the injected lesson's commands reproduced in the answer.
Read the setup before the number: the scenario in this benchmark is each lesson's own title, the injected
lesson is *that same lesson*,
no retrieval call is made, and correctness is not checked. It measures the **recitation** half of RAG:
necessary for MisakaNet to help, and **not evidence that search finds anything**.

The run is **paused**. Two independent runs of ≈500 scenarios each on 2026-09-22: **46.1%** with the
lesson pasted in, **23.3%** without. What remains is the last snapshot plus its dated record —
[`docs/benchmarks/latest.json`](docs/benchmarks/latest.json).

The table below is generated by [`scripts/update_readme_benchmark.py`](scripts/update_readme_benchmark.py);
do not hand-edit it.

<!-- BEGIN generated: benchmark-trend -->

| 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
```

<!-- END generated: benchmark-trend -->

Per-run files: [`docs/benchmarks/`](docs/benchmarks/) · metric definition: `METRIC_DEFINITION` in
[`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py).

## Take part

**1. Report a failure the corpus does not have.** Search first, then call `misakanet_submit_intake` —
no account, no email, no token, a five-line report is enough. It becomes a tracked issue.

**2. Reuse a lesson and leave the trace.** A "this helped" vote is recorded as an `E3` hint, not as
proof. The proof is quieter: your retrieval is counted, anonymously, as one more distinct client.

**What you get back: attribution.** A lesson cites the intake that produced it (`source:`,
`provenance.issue:`), and the pipeline can emit a receipt naming the lesson and its evidence level.

Nothing here is a bounty: this repository pays nothing and promises nothing. Some issues carry
third-party reward banners added by our own automation; we do not administer them — see
[Contributing](#contributing).

## How to use it

Pick one channel; they are independent.

| I want… | Command | What it touches |
|---|---|---|
| my assistant to search the lessons | `npx @misaka-net/misakanet-setup` | writes the MCP endpoint into each assistant's config; optionally a rules block and a hook |
| **Claude Code**, as a plugin | `/plugin marketplace add Ikalus1988/MisakaNet` then `/plugin install misakanet@misakanet` | the hosted MCP tools, no installer, no local process |
| **DeepSeek Harness** | `dsh plugin --profile web add misakanet` | `mcp__misakanet__*` tools plus the session panel |
| to call the endpoint myself | the `curl` in [Your first five minutes](#your-first-five-minutes) | nothing |
| the library in my own code | `pip install misakanet-core` | nothing |

**The two-package trap** (it cost a real install failure, #1849):

| Looks like | Actually is | Use it for |
|---|---|---|
| `@misaka-net/misakanet-setup` (npm) | the **installer** — has `bin`, no plugin entry | teaching your assistant to search |
| `misakanet` (npm) | the **DSH / Codex plugin** | `dsh plugin --profile web add misakanet` |
| this repository (git) | also a **Claude Code plugin marketplace** | `/plugin marketplace add Ikalus1988/MisakaNet` |
| `misakanet` (PyPI) | the stdio **MCP server** | `python3 -m misakanet.server` |
| `misakanet-core` (PyPI) | the **library** (stdlib-only BM25) | `from misakanet.search import search_lessons` |

**Reads are anonymous and unlimited** (a per-address burst window is a speed limit, not a quota).
**Registration is for writing**: it unlocks `misakanet_write_lesson` and `misakanet_preflight`
([why](AGENTS.md#33-注册与配额)).

Verify an install with `npx @misaka-net/misakanet-setup --verify`; undo it with `--uninstall`.
Prerequisites: Node ≥ 18 for the installer, Python ≥ 3.10 for the library and stdio server.

### Use it as a GitHub Action

When a workflow fails, the action searches the lessons and comments the closest match on the pull
request (optionally reporting the new error). Published on
[GitHub Marketplace](https://github.com/marketplace/actions/misakanet-intake-bot).

```yaml
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 }}
```

→ [inputs and outputs](docs/agents/external-usage.md)

## Documentation

| Topic | Where |
|---|---|
| Install, verify, uninstall | [docs/quickstart.md](docs/quickstart.md) · <https://misakanet.org/install/> |
| MCP: protocol, tools, transports | [docs/mcp.md](docs/mcp.md) · [API.md](API.md) |
| CLI | [docs/cli-reference.md](docs/cli-reference.md) · `python3 search_knowledge.py "…"` |
| Architecture | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) |
| Contributing a fix | [CONTRIBUTING.md](CONTRIBUTING.md) · [label system](docs/label-system.md) |
| Submitting an intake | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) · [mcp-remote](docs/integrations/mcp-remote.md) |
| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
| Known limitations | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
| Benchmarks | [docs/benchmarks/](docs/benchmarks/) |
| Roadmap / changelog | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
| Competitors, domains, crawler policy | [competitive](docs/competitive-analysis.md) · [domains](docs/domains/) · [robots](docs/cloudflare-robots-txt.md) |

## Contributing

> **Zero bounty. Maximum rigor. Merge earns credit.**

"Zero bounty" is a statement about *this repository*: MisakaNet pays nothing and promises nothing. It
is not a statement about the issue you are looking at. Some issues carry an **Opire** banner
advertising a third-party reward, added automatically by our own
[`scripts/question_autopilot.py`](scripts/question_autopilot.py) — we do not administer those payouts,
and Opire is not mentioned in `CONTRIBUTING.md`. **Verify any reward offer independently** before you
plan work around it. The only thing this repository has ever honoured is a merged PR.
([#2903](https://github.com/Ikalus1988/MisakaNet/issues/2903))

1. Check the checkout: `python3 scripts/misakanet_cli.py smoke`
2. Search before writing: `python3 search_knowledge.py "your error here"`
3. Found nothing? [Share your failure lesson](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — five lines is enough

→ [CONTRIBUTING.md](CONTRIBUTING.md) · [good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) · [code of conduct](CODE_OF_CONDUCT.md)

## Security

⚠️ **Sandbox your agent before executing retrieved commands.** Lessons are community-contributed —
review before running. CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick
injection). See [SECURITY.md](SECURITY.md) and [LIMITATIONS.md](docs/LIMITATIONS.md).

## Troubleshooting

| Symptom | Where |
|---|---|
| DCO · leaked token · pip timeout · `database locked` · Windows/GBK · WSL permission · FANUC codes | [docs/troubleshooting.md](docs/troubleshooting.md) |
| MCP returns 403/405, or a client shows no tools | [docs/mcp.md](docs/mcp.md) · [FAQ.md](FAQ.md) |
| Behind a corporate proxy | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) |

## For Agents & Crawlers

**Prefer MCP intake for missing or stale lessons; PRs are optional.** Search first; if nothing matches,
call `misakanet_submit_intake` at `https://misakanet.org/mcp` — no account, no token. Never send
secrets or raw private logs. Protocol: [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md).

## Contributors

<a href="https://github.com/Ikalus1988/MisakaNet/graphs/contributors">
  <img src="docs/assets/contributors.svg" alt="MisakaNet contributors" />
</a>

*Built by the network, for the network. Zero bounties paid — only merge approval and eternal network gratitude.* ⚡

## License

[Apache-2.0](LICENSE) — Copyright 2026 Ikalus1988. Lessons are contributed under the same license, and
every commit carries a DCO `Signed-off-by` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
