Skip to content

quickstart.md

Latest commit

 

History

History
268 lines (195 loc) · 8.12 KB

quickstart.md

File metadata and controls

268 lines (195 loc) · 8.12 KB
Raw

Use MisakaNet in 5 Minutes

Two tracks to start with — pick one, 30 seconds each — then three deeper steps: search, contribute, integrate.

Track A — Let your assistant search (30 seconds)

For Claude Code / Codex / Hermes / OpenClaw / codewhale. The installer writes the MCP endpoint into each assistant's own config; it does not install anything behind your back.

  1. Install the endpoint into every assistant you use:

    npx @misaka-net/misakanet-setup

  2. Close and reopen your assistant window, then confirm the endpoint landed:

    npx @misaka-net/misakanet-setup --verify

  3. Ask something only a lesson can answer. Paste the rawest fragment of an error — switch vision model, context window exceeded, tool call permission denied — and the assistant should search the lessons before it answers.

    Check: claude mcp list (or codex mcp list) lists misakanet with 7 tools. Nothing to undo? npx @misaka-net/misakanet-setup --uninstall.

Track B — Call the endpoint yourself (30 seconds)

No install and no account: the read tools are open, and only a per-address burst limit applies — a speed limit, not a quota.

  1. Search:

    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 the answer. A hit returns structuredContent.results[], each with id, title and a truncated problem:

    {"structuredContent":{"source":"worker-bm25",
  "results":[{"id":"hermes-state-database-lock-issues-cleanup-protocol",
              "title":"Hermes State Database Lock Issues - Cleanup Protocol"}]}}

    No hit returns "no_match": true plus a ready-to-send intake object naming misakanet_submit_intake — that is a useful answer too, not an error.

  3. Need the write tools (misakanet_write_lesson, misakanet_preflight)? Register once, then keep the token for later calls:

    curl -sS https://misakanet.org/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_register","arguments":{"agent_type":"your-agent"}}}'

The same six steps are on the home page. The commands are mirrored there on purpose — a static HTML page cannot include Markdown — and #1895 adds the check that keeps both copies byte-identical, so a change here cannot silently miss the page.

Step 1: Search for a Lesson (30 seconds)

Option A — Local Python:

git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet
pip install misakanet-core
python3 search_knowledge.py "database is locked"

Option B — Docker (no local Python needed):

docker pull ghcr.io/ikalus1988/misakanet:latest
docker run -i ghcr.io/ikalus1988/misakanet:latest search_knowledge.py "database locked"

Use Docker for: CI smoke tests, isolated trials, or Claude Desktop MCP config with containerized server.

Windows user? Run this once to avoid vim popping up during git pull / rebase:

git config --global pull.rebase true
git config --global core.editor "notepad"

This also works for VS Code: git config --global core.editor "code --wait"

Expected output:

┌─ Results for: database is locked ─────────────────────────────┐
│ #  Score  Domain        Title                                  │
│ 1  0.89   agent-net     hermes-state-database-lock-cleanup     │
│ 2  0.74   infra         sqlite-wal-mode-crash-recovery         │
│ 3  0.61   contrib       agent-state-database-lock-cleanup      │
└───────────────────────────────────────────────────────────────┘

Useful flags:

Flag Effect
--top=5 Limit results
--domain=infra Filter by domain
--lang=en English results only
--titles One line per result

Common failure: ModuleNotFoundError: No module named 'misakanet_core'.

Fix: pip install misakanet-core (not misakanet). The core engine is a separate PyPI package.

Step 2: Contribute a Lesson (2 minutes)

Option A — PR via API (no fork needed):

python3 scripts/queue_lesson.py \
  -t "SQLite WAL mode crash on NFS" \
  -d infra \
  "Root cause: SQLite WAL mode requires POSIX locks. NFS does not support them.
   Fix: switch to DELETE journal mode: PRAGMA journal_mode=delete.
   Verification: run 100 concurrent writes on NFS mount, no crash."

This creates a Markdown file under lessons/contrib/ and opens a PR automatically.

Option B — Manual PR:

# 1. Fork the repo on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USER/MisakaNet.git && cd MisakaNet

# 3. Create a lesson file
cat > lessons/contrib/my-error-fix.md << 'EOF'
---
title: "Fix: Your Error Here"
domain: general
tags: [your-tags]
status: published
---

## Problem
Describe the error.

## Root Cause
What actually caused it.

## Solution
Copy-pasteable fix commands.

## Verification
How to confirm the fix works.
EOF

# 4. Push and open PR
git checkout -b fix/my-error
git add lessons/contrib/my-error-fix.md
git commit -m "feat: add lesson for my-error-fix"
git push origin fix/my-error
# Then open PR on GitHub targeting Ikalus1988/MisakaNet main

Lesson quality checklist (see docs/lesson-checklist.md for full list):

  • Exact error message or traceback included
  • Root cause explained (not just "it broke")
  • Solution is copy-pasteable
  • Verification steps confirm the fix

Step 3: Integrate with Your Agent (2 minutes)

Python (LangChain):

from misakanet.tools.langchain_tool import MisakaNetSearchTool

tool = MisakaNetSearchTool()
results = tool._run("database locked")
print(results)

MCP Server (for Claude Code, Cursor, etc.):

# Start the MCP server
python3 scripts/mcp_server.py

# In your MCP client config:
{
  "mcpServers": {
    "misakanet": {
      "command": "python3",
      "args": ["scripts/mcp_server.py"],
      "cwd": "/path/to/MisakaNet"
    }
  }
}

Direct import (no framework):

from misakanet_core import BM25, tokenize

# Load lessons, tokenize, search
# See misakanet/search/engine.py for the full API

Common failure: ModuleNotFoundError: No module named 'misakanet'.

Fix: run pip install -e . from the repo root, then retry.

What's Next?

Goal Go to
Understand the architecture docs/CONCEPTS.md
Set up a federation node AGENTS.md §3.3
Run the benchmark suite scripts/bench_orchestrator.py
Join the network JOIN.md

What a lesson looks like (three real ones)

rag — ChromaDB crash on NTFS

Problem: ChromaDB SQLite backend fails on NTFS-mounted WSL paths. Fix: Move DB to ext4: mv ~/.chromadb /mnt/ext4/. Verify: python3 -c "import chromadb; c=chromadb.Client(); print(c.heartbeat())".

devops — WSL terminal underscore corruption

Problem: WSL terminal paste swallows underscores under high load. Fix: Use tmux or pipe stdin via temp script files. Verify: echo "test_underscore_command" shows correct output.

fanuc — Karel ERR_ABORT vs ERR_PAUSE

Problem: Robot hard-aborts instead of pausing on error. Fix: Use POST_ERR(..., ERR_PAUSE) (value 1) instead of ERR_ABORT (value 2). Verify: Robot pauses, system stays responsive.

More best practices for ci, claude, docker, feishu, mcp, network → docs/domains/

→ 更多按主题整理的课程：docs/domains/ · 全库检索：https://misakanet.org/search/