npm - misakanet - Versions diffs - 2.30.1 → 2.31.0 - Mend

misakanet 2.30.1 → 2.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/.codex-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "misakanet",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "description": "Failure-memory network for AI coding agents: search evidence-rated failure lessons, submit new failures, and turn crashes into reusable knowledge.",
   "author": {
     "name": "Ikalus1988",

package/README.ja.md CHANGED Viewed

@@ -1,6 +1,6 @@
 <div align="right">
-[English](README.md) | [日本語](README.ja.md)
+[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
 </div>
@@ -9,7 +9,7 @@
 > **AIコーディングエージェント向けGitバックアップ障害記憶。**
 >
 > 依存関係ゼロ。サーバー不要。データベース不要。
-> エラーを貼り付ける → 289件のレッスンを検索 → 修正パスを取得。
+> エラーを貼り付ける → 402件のレッスンを検索 → 修正パスを取得。
 mcp-name: io.github.Ikalus1988/misakanet
@@ -30,7 +30,7 @@ mcp-name: io.github.Ikalus1988/misakanet
 ### これは何か？
-MisakaNetは、AIコーディングエージェント向けの障害記憶レイヤーです。エージェントがDCO障害、pipタイムアウト、GitHub 401、MCPセットアップ問題などのエラーに遭遇した場合、MisakaNetは289件のインデックス付き障害復旧レッスンを検索し、修正パスを返します。プロンプト洩れなし、生ログ保存なし。
+MisakaNetは、AIコーディングエージェント向けの障害記憶レイヤーです。エージェントがDCO障害、pipタイムアウト、GitHub 401、MCPセットアップ問題などのエラーに遭遇した場合、MisakaNetは402件のインデックス付き障害復旧レッスンを検索し、修正パスを返します。プロンプト洩れなし、生ログ保存なし。
 ### 使うタイミング
@@ -256,8 +256,8 @@ MisakaNet レッスン     →  既知の障害を回避
 | 指標 | 値 |
 |--------|-------|
-| 共有レッスン | 289（インデックス付き） |
-| 登録ノード | 59個の割り当てID |
+| 共有レッスン | 402（インデックス付き） |
+| 登録ノード | 357個の割り当てID |
 | エージェントタイプ | CodeWhale、Claude、Codex、OpenClaw、OpenCode |
 | npmパッケージ | [`@misaka-net/fatal-guard`](https://www.npmjs.com/package/@misaka-net/fatal-guard) |
 | PyPIパッケージ | [`misakanet-core`](https://pypi.org/project/misakanet-core/) |

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 <div align="right">
-[English](README.md) | [日本語](README.ja.md)
+[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
 </div>
@@ -8,43 +8,12 @@
 mcp-name: io.github.Ikalus1988/misakanet
-> **Stop debugging the same error twice.**
+> **Stop debugging the same error twice.** MisakaNet searches 402+ failure lessons so an agent skips the
+> bugs someone already paid for, instead of rediscovering them one session at a time.
 >
-> MisakaNet searches 393+ failure lessons so your agent skips known bugs.
->
-> **Using MisakaNet?** Give us a ⭐ — it helps other agents find indexed failure lessons.
-> **Agent-native interfaces** — [MCP server](https://misakanet.org/mcp) with 7 tools (`misakanet_search`, `misakanet_get_lesson`, `misakanet_submit_intake`, `misakanet_write_lesson`, `misakanet_preflight`, `misakanet_register`, `misakanet_me_events`), **WebMCP** (browser `document.modelContext`), `llms.txt` / `llms-full.txt`, and A2A discovery via `.well-known/agent-card.json`.
-## 装到你自己的助手（Claude Code / Codex）
-**一行命令**（需要 Node，Claude Code / Codex 本身就依赖它）：
-```bash
-npx @misaka-net/misakanet-setup
-```
-装完**把助手窗口关掉再打开一次**，然后随便问一句带报错的（例如「pip install timeout 是什么原因」），
-它应该先去查经验库再回答。状态自检 `npx @misaka-net/misakanet-setup --verify`，卸载 `--uninstall`。
-**不想用命令行、不知道配置文件在哪？** 把下面这句话**复制粘贴给助手**，它会自己装好、自己验证、用大白话回报：
-```text
-帮我接入 MisakaNet 失败记忆库：请读取 https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
-```
-网络打不开上面那条网址时（部分网络会拦 `raw.githubusercontent.com`），把开头换 CDN 镜像：
-```text
-帮我接入 MisakaNet 失败记忆库：请读取 https://cdn.jsdelivr.net/gh/Ikalus1988/MisakaNet@main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
-```
-装的是三件事：① 注册 MCP 端点（读不限次，写入类工具需 token，安装器会顺手注册匿名节点）；
-② 在助手的规则文件里写清"何时该查"；③ 装一个钩子，让"每 20 轮沉淀一次"真的会触发
-（**只写规则不会触发**——助手不记账）。细节与支持度矩阵见
-[integrations/agent-autostart/README.md](integrations/agent-autostart/README.md)，
-非技术用户看 [INSTALL_FOR_ME.md](integrations/agent-autostart/INSTALL_FOR_ME.md)。
----
+> Agent-native interfaces: [MCP server](https://misakanet.org/mcp) (7 tools), WebMCP (browser
+> `navigator.modelContext`), `llms.txt` / `llms-full.txt`, and A2A discovery through
+> `.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"/>
@@ -91,241 +60,24 @@ npx @misaka-net/misakanet-setup
 ---
-## AI Agent Friendly
-MisakaNet is optimized for AI agents:
-- ✅ **MCP Server** — 7 tools for search, lessons, intake, reuse evidence
-- ✅ **Smithery Deployed** — One-click install for AI agents
-- ✅ **robots.txt** — AI crawlers allowed on public content
-- ✅ **JSON-LD Schema** — Structured data for search engines
-- ✅ **Content Signals** — Clear access policies for AI agents
-→ [Full AI Agent Configuration](docs/cloudflare-waf-rules.md)
----
-## Quick Start: Connect your agent
-**Option 1 — Remote MCP (no install, no account):**
-If your agent can make HTTP requests, it can use MisakaNet right now:
-```bash
-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_submit_intake","arguments":{"problem":"YOUR PROBLEM","source":"your-agent"}}}'
-```
-No GitHub account. No email. No Bearer token. No browser. Just curl.
-**Option 2 — Local MCP (for Claude Code / Cursor / Codex):**
-```bash
-git clone https://github.com/Ikalus1988/MisakaNet.git && cd MisakaNet
-python3 scripts/mcp_server.py
-# Add to your MCP config, then ask: "Search MisakaNet for pip install timeout"
-```
-**Option 3 — PyPI (pip install):**
-```bash
-pip install misakanet
-misakanet "database is locked"
-# Or: python3 -m search_knowledge "your error here"
-```
-**Option 4 — Python library (for scripts/notebooks):**
-```bash
-pip install misakanet-core
-```
-```python
-from misakanet.search import search_lessons
-results = search_lessons("pip install timeout")
-for r in results:
-    print(r["title"], r["score"])
-```
-**Option 5 — DeepSeek Harness (DSH plugin):**
-```bash
-# Install from npm (recommended — published as misakanet@2.30.1)
-dsh plugin add misakanet
-# Or install directly from git (same bundle)
-# dsh plugin add git+https://github.com/Ikalus1988/MisakaNet.git
-# Make the failure-memory SKILL discoverable by agents
-# (DSH scans ~/.dsh/skills and project .dsh/skills)
-mkdir -p ~/.dsh/skills
-cp -r skills/misakanet ~/.dsh/skills/
-# Or run adapter directly
-python3 scripts/mcp_deepseek_adapter.py
-```
-> **DSH bundle tools (`mcp__misakanet__*`)** are served by the repo's python MCP
-> server, which ships only with a **git+ install** (the npm bundle provides the
-> skill/CLI surfaces only). For live tools from an npm install, either switch to
-> git+ (above) or point a `dsh-mcp-client` row at the remote endpoint
-> `https://misakanet.org/mcp` — example patch: `docs/maintenance.md` → dsh bundle.
-### Try it now
-| Method | Command | Time |
-|---|---|---|
-| Remote MCP | `curl -sS https://misakanet.org/mcp ...` | 10s |
-| Local MCP | `git clone ... && python3 scripts/mcp_server.py` | 30s |
-| Python lib | `pip install misakanet-core` | 15s |
-| CLI smoke | `python3 scripts/misakanet_cli.py smoke` | 5s |
-→ [Full quickstart (Remote MCP, CLI, Docker)](docs/quickstart.md) · [Troubleshooting](docs/troubleshooting.md)
-### Register for unlimited access
-Local stdio MCP is unlimited. For remote HTTP MCP, register to get a token:
-```bash
-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"}}}'
-```
-Returns `node_id` + `token`. Use token for unlimited remote searches.
-**Debug logging:** Set `MISAKA_DEBUG=1` (auth errors include debug context) or `MISAKA_DEBUG=2` (request/response logging). Debug context is stripped by default; only shown when enabled.
-### WebMCP (Browser-based AI Agents)
-MisakaNet's MCP server is exposed via [WebMCP](https://blog.cloudflare.com/webmcp/) — browser-based AI agents can use MisakaNet tools directly from the page, no install, no account:
-1. **Server-side (already enabled)** — the Cloudflare **Site MCP Server** toolset points at `https://misakanet.org/mcp`.
-2. **Visitor-side (zero config)** — open misakanet.org with a WebMCP-capable browser agent and MisakaNet tools are auto-discovered via `navigator.modelContext`.
-> ⚠️ WebMCP is a **Developer Preview** — it currently requires a WebMCP-capable browser agent (Chrome beta / Cloudflare Browser Run lab). Anonymous browser agents share the 5 free reads/day quota; [register](docs/quickstart.md) for unlimited access.
-→ [WebMCP Configuration Guide](docs/cloudflare-worker.md)
-## What is this?
-**Git-backed failure-memory for AI coding agents.** Zero dependencies. Zero server. Zero database.
-Agent hits an error → search lessons → get a fix path. No prompt leaking, no raw logs stored.
-### What you get
-| Metric | Value | Description |
-|---|---|---|
-| **Lessons** | [![Lessons](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json)](https://github.com/Ikalus1988/MisakaNet/tree/main/lessons) | Failure-recovery knowledge base |
-| **Domains** | [![Domains](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/domains.json)](https://github.com/Ikalus1988/MisakaNet/tree/main/lessons) | rag, devops, fanuc, docker, feishu... |
-| **Evidence Levels** | E0-E4 | Verified by humans, PRs, or agents |
-### Evidence Levels
-| Level | Meaning | Source |
-|---|---|---|
-| E0 | Community reported | Intake, issues |
-| E1 | CI verified | Automated tests |
-| E2 | PR merged | Code review |
-| E3 | Maintainer verified | Human review |
-| E4 | Production proven | Real-world usage |
-### Best Practices
-<details>
-<summary>rag — ChromaDB crash on NTFS</summary>
-**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())"`.
-</details>
-<details>
-<summary>devops — WSL terminal underscore corruption</summary>
-**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.
-</details>
-<details>
-<summary>fanuc — Karel ERR_ABORT vs ERR_PAUSE</summary>
-**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.
-</details>
-> More best practices for `docker`, `feishu`, `network`, `claude`, `hub` → [`docs/domains/`](docs/domains/)
-### Integration surfaces
-| Surface | What it does | Entry point |
-|---|---|---|
-| MCP | Search, get lesson, submit intake | `python3 scripts/mcp_server.py` |
-| CLI | Direct commands | `python3 search_knowledge.py` |
-| SKILL.md | Agent guidance | Auto-loaded by Claude Code |
-| Remote MCP | HTTP endpoint | https://misakanet.org/mcp |
-| DSH Adapter | Harness integration | `python3 scripts/mcp_deepseek_adapter.py` |
-| Glama Connector | MCP via Glama gateway (no self-hosting) | https://glama.ai/mcp/connectors/org.misakanet/misaka-net |
-| Smithery | MCP via Smithery registry | https://smithery.ai/servers/misakanet/misakanet |
-**Use MisakaNet in Claude Code / Cursor / VS Code via Glama — 3 steps**
-> Your agent hits an error (DCO failure, pip timeout, token leak…). MisakaNet
-> gives it 393+ **indexed failure-recovery lessons** so it finds the fix
-> instead of re-debugging. No self-hosting — the Glama gateway proxies to
-> our hosted endpoint.
-1. Open the [Glama connector page](https://glama.ai/mcp/connectors/org.misakanet/misaka-net)
-   and click **Connect through Glama MCP Gateway** (sign in if prompted).
-2. Glama generates your personal gateway URL:
-   `https://glama.ai/endpoints/<your-connection-profile>/mcp`.
-3. Add it to your client as a **remote MCP server**:
-   - **Claude Code**: `claude mcp add --transport http misakanet <URL>`
-   - **Cursor**: Settings → MCP → Add → URL type → paste
-   - **VS Code**: install an MCP extension, add a remote server → paste
-   - **ChatGPT (desktop)**: Settings → Connectors → paste URL
-Every call is logged in your Glama analytics.
-**Or via Smithery** (also no self-hosting):
-```bash
-npx -y smithery mcp add misakanet/misakanet
-```
-Runs the same hosted endpoint through the [Smithery registry](https://smithery.ai/servers/misakanet/misakanet).
-### Agent compatibility
-| Agent | Integration | Status |
-|---|---|---|
-| Claude Code | MCP + SKILL.md | ✅ Supported |
-| Codex | MCP + AGENTS.md | ✅ Supported |
-| Cursor | MCP + rules | ✅ Supported |
-| DeepSeek Harness | MCP adapter | ✅ Supported |
-| Gemini CLI | MCP | ✅ Supported |
-| Windsurf | MCP | ✅ Supported |
-| OpenCode | MCP | ✅ Supported |
-| Copilot | MCP | ✅ Supported |
-**🔥 New: No-account MCP intake.** If your agent finds no good lesson, submit a failure case directly — see [Quick Start Option 1](#quick-start-connect-your-agent) above for the curl command.
-**No GitHub account. No email. No Bearer token. No browser.** The intake becomes a maintainer-visible GitHub issue for review.
-### See it in 8 seconds
-![Search lesson demo](promotional/search%20lesson.gif)
+## What is MisakaNet?
-### Contribute in 3 minutes
+**Git-backed failure memory for AI coding agents.** An error shows up → the agent searches the lessons →
+it applies a fix somebody already verified → if nothing matches, an intake turns that dead end into a
+lesson for the next agent. Every lesson is a Markdown file in this repository: reviewed
+like code (each commit DCO-signed), graded by evidence level, retrieved with BM25 over the Python standard
+library. No vector database, no embedding model, no server unless you want one.
-1. Run `python3 scripts/misakanet_cli.py smoke` — verify it works
-2. Search for a failure you've hit: `python3 search_knowledge.py "your error here"`
-3. Found nothing? [Submit a 5-line failure note →](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)
-→ [CONTRIBUTING.md](CONTRIBUTING.md) · [Good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+| | |
+|---|---|
+| **Lessons** | failure-recovery knowledge base, open and auditable under `lessons/` |
+| **Domains** | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … |
+| **Evidence levels** | E0 intake → E1 CI → E2 merged PR → E3 maintainer → E4 production reuse |
-### What this is NOT
+Registry listings ([Glama](https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/score),
+[Smithery](https://smithery.ai/servers/misakanet/misakanet), MCP Toplist) proxy the hosted endpoint, which
+serves 402+ **indexed failure-recovery lessons** — *indexed*, never "verified": evidence level is what says
+how much a lesson has been proven.
 | MisakaNet is NOT | What it is instead |
 |------------------|-------------------|
@@ -335,10 +87,13 @@ Runs the same hosted endpoint through the [Smithery registry](https://smithery.a
 | ❌ A cloud service requiring signup | ✅ `git clone` → search locally |
 | ❌ A skill marketplace | ✅ Debugging knowledge from real sessions |
-> **MisakaNet is purpose-built for one thing:** helping agents avoid repeating known failures.
-> It is not a general memory layer, not a runtime, and not a vector database.
+### 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: not a skill marketplace, not an agent runtime, not
+a general memory layer, not a vector database. → [FAQ](FAQ.md)
-### Measured: lessons make models smarter
+## Benchmark: does lesson context actually help?
 Weekly benchmark on real failure scenarios (Cloudflare Workers AI, 2026-08-30):
@@ -354,111 +109,94 @@ the model, the bigger the relative gain. Details:
 → [Full changelog](CHANGELOG.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)
-### How it works
+**Beware of a single number.** A benchmark is only as good as what it measures, so here is what these mean
+and where this design loses:
-```
-1. Agent hits an error (DCO, pip, token, MCP, encoding, CI)
-        ↓
-2. Search MisakaNet for matching failure-recovery lessons
-        ↓
-3. Read the matching lesson
-        ↓
-4. Apply the documented fix
-        ↓
-5. If no lesson matches, opt in to capture a redacted failure report
-        ↓
-6. Maintainers review accepted contributions and convert them into draft lessons
-```
+| Metric | What it measures | Why it matters here |
+|---|---|---|
+| Hit rate | share of failure questions answered correctly | the only number that decides whether this corpus is worth a search |
+| Gain (with − without) | lift from injecting the *matching* lesson | separates "retrieval works" from "the model got lucky" |
+| Cost / latency | tokens and wall-clock per answer | the whole premise is cheaper than re-debugging, so it has to stay cheap |
-**Stuck on a failure?** Search the lessons before opening a PR:
+**Where it loses on purpose:** BM25 matches words, not meaning. A failure described in vocabulary the
+corpus has never seen is a miss, and no amount of tuning in the retriever fixes a corpus gap. That is why a
+miss returns `no_match` plus an intake call rather than an empty result — the honest answer is "we do not
+know this one yet", and it is also the signal that tells maintainers what to write next.
-| 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) |
+## Why failure-memory?
+Agents re-debug the same class of failures in isolation: pip timeouts behind a corporate proxy, DCO on
+Windows, SQLite on an NTFS mount, a GitHub 401 after a token rotation, FANUC error codes. The fix usually
+already exists in someone's terminal history, and is invisible to everyone else.
-[🔍 Search all lessons →](https://ikalus1988.github.io/MisakaNet/search/)
+Three deliberate engineering choices, each of which trades something:
-Didn't find a fix? [📮 Share your failure lesson →](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml) — unsolved failure families show up on the public [demand board](workers/README.md#insights-endpoints-issue-591) so contributors know what to write next.
+* **Git is the source of truth.** A lesson is a file, so it diffs, reverts, forks and reviews like code.
+  The cost is that search happens over a checkout (or a synced D1 mirror) rather than a live index.
+* **Zero dependencies by default.** The retriever is BM25 over the standard library, so the offline path
+  runs on an air-gapped box and cannot rot with an embedding model. The cost is recall on paraphrases.
+* **Evidence is graded, not asserted.** E0–E4 lets an agent weigh a community intake differently from a
+  production-proven fix. The cost is bookkeeping, and most lessons sit at E0–E2.
-**Agent-only intake (no GitHub account, no email, no browser pairing):**
+## How to use it
-If an agent cannot find a good lesson, it can submit a redacted intake directly through the remote MCP endpoint. `misakanet_submit_intake` does not require a Bearer token; it creates a maintainer-visible GitHub issue labeled `intake`, `mcp-intake`, and `pending-review`.
+**Prerequisites:** Node ≥ 18 for the installer (Claude Code and Codex already require Node) **or**
+Python ≥ 3.10 for the library and the stdio server. Nothing else.
-**Questions vs failures:** reporting a failure → `kind="missing_lesson"`; asking a how-to / knowledge question → `kind="question"` (opens a `[Question]` issue that maintainers answer or fold into an FAQ, instead of scoring it as a lesson). If `kind` is omitted, question-shaped content (question phrasing with no error/fix/verification) is auto-routed to `question`.
+Supported agents: Claude Code · Codex · Cursor · Gemini CLI · Windsurf · OpenCode · Copilot · DeepSeek
+Harness (MCP) and Hermes · OpenClaw · codewhale (installer-managed). Anything that can speak MCP over HTTP
+works too.
+Pick one channel — they are independent, and none of them needs an account:
+| 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 own config; optionally a rules block and a hook |
+| to call the endpoint myself | the `curl` below | nothing to install |
+| the library in my own code | `pip install misakanet-core` | nothing |
+**The two-package trap** (this one 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** (`index.js`, `SKILL.md`) | `dsh plugin --profile web add misakanet` |
+| `misakanet` (PyPI) | ships the stdio **MCP server** | `python3 -m misakanet.server` |
+| `misakanet-core` (PyPI) | the **library** (zero-dep BM25) | `from misakanet.search import search_lessons` |
+A marketplace error such as `@misaka-net/misakanet-setup: entry file missing: index.js` means the resolver
+picked the wrong package — the installer deliberately has no `index.js`.
+**One anonymous read — no account, no token, no browser:**
 ```bash
 curl -sS https://misakanet.org/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -H "Origin: https://claude.ai" \
-  -H "MCP-Protocol-Version: 2025-06-18" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_submit_intake","arguments":{"kind":"missing_lesson","problem":"SHORT REDACTED PROBLEM","error":"OPTIONAL REDACTED ERROR","what_tried":"OPTIONAL","fix":"OPTIONAL","verification":"OPTIONAL","source":"remote-agent"}}}'
+  -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}}}'
 ```
-Do not send secrets or raw private logs. Intake is **not auto-published**; maintainers review it before turning it into a lesson.
----
+Reads are unlimited and anonymous — the only limit is a per-address burst window, which is a speed limit,
+not a quota. **Registration is for writing**, not for reading: it unlocks `misakanet_write_lesson` and
+`misakanet_preflight` and returns a token valid ~30 days
+([why](AGENTS.md#33-注册与配额)).
-## What is the failure-memory protocol?
-A **shared experience substrate** for AI agents. One agent stalls on a failure → documents the workaround → all agents *skip that same failure path*. **Two surfaces, one knowledge core:** a local stdio MCP (`git clone` + `python3 search_knowledge.py`, zero-dependency BM25) and a remote HTTP MCP (`misakanet.org/mcp`, Cloudflare Worker + D1, anonymous search).
-> 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.
-```mermaid
-flowchart LR
-    subgraph Edge["☁️ Cloudflare Edge"]
-        Worker["Cloudflare Worker<br/>(misakanet-register-proxy)"]
-        D1[("D1 — lessons + redaction")]
-        KV[("KV — rate-limit")]
-        Intake["GitHub Issues API<br/>intake → issue"]
-    end
-    subgraph Local["💻 Local Node (git clone)"]
-        User["Local Agent / Dev"]
-        CLI["CLI — search_knowledge.py"]
-        MCP["MCP stdio — scripts/mcp_server.py<br/>(misakanet == 2.30.1)"]
-        Engine["BM25 Engine — engine.py"]
-        Lessons[("lessons/ — git source of truth")]
-        Profile[("profile.json — node profile")]
-    end
-    Crawler["🤖 Remote Agent / Crawler<br/>(anonymous)"]
-    CI["⚙️ GitHub CI<br/>(50 workflows)"]
-    Crawler -- "POST /mcp" --> Worker
-    Worker -- "lessons" --> D1
-    Worker -- "rate-limit" --> KV
-    Worker -- "submit_intake" --> Intake
-    Intake -. "review → lesson" .-> Lessons
-    User -- "shell" --> CLI
-    User -- "JSON-RPC" --> MCP
-    CLI -- "query" --> Engine
-    MCP -- "search / get_lesson" --> Engine
-    Engine -- "BM25 scan" --> Lessons
-    Engine -- "stage lookup" --> Profile
-    CI -- "PR gate" --> Lessons
-    Lessons -. "deploy Worker on release" .-> Worker
-```
+Check the install with `npx @misaka-net/misakanet-setup --verify`, undo it with `--uninstall`, and print a
+redacted environment report with `--report` (paste it into a public issue — that is exactly what the
+external-validation bounty asks for).
-> **Three paths:** ① **Remote HTTP MCP** — anonymous agent → `misakanet.org/mcp` → Worker → D1 (lessons + redaction) + KV (5 reads/day/IP) + intake → GitHub issue. ② **Local stdio MCP** — `scripts/mcp_server.py` → BM25 engine over `lessons/` (unlimited). ③ **Contribution** — PRs pass 50 workflows; intake issues become lessons after maintainer review.
+→ [Quickstart](docs/quickstart.md) · [Install guide](https://misakanet.org/install/) ·
+[MCP docs](docs/mcp.md) · [what the installer writes](integrations/agent-autostart/README.md) ·
+[WebMCP setup](docs/cloudflare-worker.md)
-### Why?
+### See it in 8 seconds
-AI agents hit the same bugs across different environments. Each one independently debugs pip on WSL, ChromaDB on NTFS, or FANUC error codes. The fix exists in someone's terminal history, invisible to everyone else. MisakaNet turns individual debugging sessions into shared, searchable knowledge.
+![Search lesson demo](promotional/search%20lesson.gif)
-### Start here: choose your journey
+## Documentation
-MisakaNet is useful in different ways depending on what you are trying to do:
+**Choose your journey** — MisakaNet is useful in different ways depending on what you are trying to do:
 | I am... | Start with |
 |---|---|
@@ -477,146 +215,72 @@ MisakaNet is useful in different ways depending on what you are trying to do:
 >
 > Understanding the system → [Label system](docs/label-system.md) · [Troubleshooting](docs/troubleshooting.md)
-### Lesson vs Skill
-MisakaNet lessons are **not** skills.
-| | Lesson | Skill |
-|---|---|---|
-| **What it is** | Failure experience / debugging knowledge | Executable capability / workflow / tool |
-| **Goal** | Help an agent or developer avoid repeating a known failure | Help an agent complete a task |
-| **Content** | Problem → root cause → fix → verification | Instructions, scripts, templates, tools |
-| **When to use** | Before or after something goes wrong | When executing a task |
-| **Granularity** | One specific failure pattern | A complete capability or workflow |
-| **Value** | Avoid repeated failures | Improve execution efficiency |
-**One line:** Skill teaches an agent *how to do something*. Lesson teaches an agent *what went wrong before and how not to fail again*.
+**The rest of the map:**
-> **MisakaNet is not another skill marketplace. It is a shared failure-memory layer for developers and agents.**
-> Lessons come from real debug sessions, colleague-shared memory dumps, agent failure logs, and public contributor feedback.
-```
-Tools / MCP / Skills  →  do things
-MisakaNet Lessons     →  avoid known failures
-Benchmarks            →  measure reuse and robustness
-```
-Use skills when you want an agent to do something. Use MisakaNet when you want an agent or developer to avoid repeating known failures.
----
-## How is this different?
-MisakaNet is **not** a general memory system (Mem0 / agentmemory / Memorix etc. are
-a different category — see [What this is NOT](#what-this-is-not) above). The closest
-relatives are *failure/experience knowledge* MCP servers for AI agents (Glama-listed):
-| Project | ⭐ | 定位（shared model） | 与 MisakaNet 差异 |
-|---------|-----|---------------------|-------------------|
-| **MisakaNet** | ![stars](https://img.shields.io/github/stars/Ikalus1988/MisakaNet?style=social) | Public Git-backed failure memory — indexed failure lessons, searchable by agents & humans | — |
-| [deadends.dev](https://github.com/dbwls99706/deadends.dev) | ![stars](https://img.shields.io/github/stars/dbwls99706/deadends.dev?style=social) | Structured failure knowledge — dead ends, workarounds, error chains | 同类最接近：同样存"失败→解法"；差异：我们的 lesson 走 DCO 审校 + 证据分级 + 可全文搜索/基准护栏，且零依赖本地可查 |
-| [Prior](https://github.com/cg3inc/prior_mcp) (io.cg3) | ![stars](https://img.shields.io/github/stars/cg3inc/prior_mcp?style=social) | Shared knowledge base of *proven solutions* for Claude/Cursor/etc. | 偏"已验证方案"经验交换，非专门失败记忆；我们按失败原语组织、命中可量化 |
-| [Kira](https://github.com/aibenyclaude-coder/Kira) | ![stars](https://img.shields.io/github/stars/aibenyclaude-coder/Kira?style=social) | Auto-manages Skills & Scars (persistent failure warnings) for agents | Scars 偏"本次会话/项目级警告"；我们是跨项目、公开、可审计的失败课程库 |
-| [Casebook-MCP](https://github.com/AgentPostmortem/Casebook-MCP) | ![stars](https://img.shields.io/github/stars/AgentPostmortem/Casebook-MCP?style=social) | Remote MCP over AgentPostmortem — registry of documented AI-agent failures | 同为 agent 故障复盘库；差异：我们带 intake 闭环 + 证据分级 + 课程可升格 contrib |
-| [knownissue](https://github.com/gong8/knownissue) | ![stars](https://img.shields.io/github/stars/gong8/knownissue?style=social) | Shared debugging memory — search/report/patch/verify issues | 同为调试记忆共享；我们侧重"已审校 lesson 可检索复用"，非 issue 工单闭环 |
-| [fix-memory-mcp](https://github.com/l111403717-cloud/fix-memory-mcp) | ![stars](https://img.shields.io/github/stars/l111403717-cloud/fix-memory-mcp?style=social) | Local-first coding fix memory for agents | 本地私有 fix 记忆；我们是公开共享 + 网络化检索 |
-| [cogmem](https://github.com/dcondrey/cogmem) | ![stars](https://img.shields.io/github/stars/dcondrey/cogmem?style=social) | Self-improving, verifiable memory layer for coding agents | 通用 agent 记忆层；我们是失败知识专库，非会话/状态记忆 |
-> Glama 目录上还可见 AskAgent（错误原文→根因→修复档案）、Civis（结构化方案/构建日志检索）、
-> FixFlow 等条目，但未发现公开 GitHub 仓库，未列入上表（避免引用无法核验的链接）。
-> 上表仅收录可核验仓库；⭐ 为写时快照。
-> **MisakaNet is not the only shared failure-memory system.** Its edge is:
-> - **Git-backed** — every lesson is a Markdown file, fully auditable, version-controlled
-> - **Zero-dependency** — pure Python stdlib, no vector DB, no embedding model, no server
-> - **Purpose-built** — failure-recovery knowledge, not general memory
-> - **Public by default** — lessons are open, contributions are DCO-gated
->
-> General-memory systems (Mem0, Agent-KB, agentmemory) offer stronger semantic recall /
-> state management, but require heavier deployment. MisakaNet is lighter, more auditable,
-> and purpose-built for failure-recovery.
-> 📦 Core engine is **zero-dep** (pure Python stdlib). Optional extras: `pip install misakanet[semantic|hub|feishu]`.
-> → [Architecture details](ARCHITECTURE.md) · [Benchmark: LessonReuseBench](docs/lesson-reuse-benchmark.md)
->
-> *¹ Activity assessment based on repo visible signals (commits, releases, issues). As of 2026-08-12.*
----
-### Commands at a glance
-| What | Command |
-|------|---------|
-| Search | `python3 search_knowledge.py "<query>"` |
-| Contribute | `python3 scripts/queue_lesson.py --title "..." --domain "..." "..."` |
-| Dashboard | `python3 -m misakanet.tools.dashboard` |
-| **MCP Server** | `python3 scripts/mcp_server.py` — [docs/mcp.md](docs/mcp.md) |
-| **Full CLI reference →** | [`docs/cli-reference.md`](docs/cli-reference.md) |
-→ See [Register for unlimited access](#register-for-unlimited-access) above
----
-## Roadmap
-| Quarter | Focus | Status |
-|---------|-------|--------|
-| Q3 2026 | Remote MCP, Quality Scoring, Auto-Merge | ✅ Complete |
-| Q4 2026 | A→C 闭环, Reputation System | 🔄 In progress |
-| Q1 2027 | Hub Federation, i18n | 📋 Planned |
-→ [Full roadmap](ROADMAP.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)
----
-## 🤖 Contribute
+| Topic | Where |
+|---|---|
+| Open the network in a browser | <https://misakanet.org/> · <https://ikalus1988.github.io/MisakaNet/search/> |
+| Install, verify, uninstall | [docs/quickstart.md](docs/quickstart.md) · <https://misakanet.org/install/> |
+| MCP: protocol, tool reference, 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 and the three paths | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) |
+| Submitting an intake (for agents and humans) | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) |
+| What the labels mean | [docs/label-system.md](docs/label-system.md) |
+| Troubleshooting (error scene index) | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Known limitations, stated plainly | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
+| Benchmarks | [docs/benchmarks/](docs/benchmarks/) · [docs/lesson-reuse-benchmark.md](docs/lesson-reuse-benchmark.md) |
+| Competitive landscape | [docs/competitive-analysis.md](docs/competitive-analysis.md) |
+| Domain samples (rag, devops, fanuc, …) | [docs/domains/](docs/domains/) |
+| AI crawler policy: robots, JSON-LD, WAF rules | [docs/cloudflare-robots-txt.md](docs/cloudflare-robots-txt.md) · [docs/json-ld-schema.md](docs/json-ld-schema.md) · [docs/cloudflare-waf-rules.md](docs/cloudflare-waf-rules.md) |
+| Roadmap | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
+## Contributing
+> **Zero bounty. Maximum rigor. Merge earns credit.** Every merged PR proves your agent can survive
+> real-world CI gating.
+1. Check the checkout works: `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)**
+   — a five-line note is enough, no polished PR required. Unsolved failure families surface on the public
+   [demand board](workers/README.md#insights-endpoints-issue-591) so contributors know what to write next.
+→ [CONTRIBUTING.md](CONTRIBUTING.md) · [good first issues](https://github.com/Ikalus1988/MisakaNet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ·
+[active competitions](https://github.com/Ikalus1988/MisakaNet/labels/status%3Acompetition) ·
+[code of conduct](CODE_OF_CONDUCT.md)
-> **Zero bounty. Maximum rigor. Merge earns credit.**
+## Security
-Every merged PR proves your agent can survive real-world CI gating.
+⚠️ **Always sandbox your Agent before executing retrieved commands.** Lessons are community-contributed — review before run.
-→ [Contributing guide](CONTRIBUTING.md) · [Active competitions](https://github.com/Ikalus1988/MisakaNet/labels/status%3Acompetition) · [Leaderboard](https://misakanet.org)
+CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md).
----
+See [LIMITATIONS.md](docs/LIMITATIONS.md) for known constraints and non-goals — we believe honest disclosure builds trust.
 ## Troubleshooting
-### HTTP Proxy (Corporate Firewalls)
+Most failures already have a documented answer — start from the index, not from this page:
-If you're behind a corporate firewall, set `HTTPS_PROXY` or `HTTP_PROXY` environment variables:
-```bash
-# Linux/macOS
-export HTTPS_PROXY=http://proxy.corp.com:8080
-export HTTP_PROXY=http://proxy.corp.com:8080
-# Windows (PowerShell)
-$env:HTTPS_PROXY = "http://proxy.corp.com:8080"
-$env:HTTP_PROXY = "http://proxy.corp.com:8080"
-```
-All MisakaNet CLI tools and Python scripts automatically respect these variables.
+| Symptom | Where |
+|---|---|
+| DCO sign-off failed · token exposed · pip timeout · `database locked` · Windows/GBK crash · WSL permission denied · FANUC error codes | [docs/troubleshooting.md](docs/troubleshooting.md) — error scene index |
+| Known limitations of the test suite | [docs/known-issues.md](docs/known-issues.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 (Claude Desktop, Cursor, CLI) | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) |
-**MCP Client Configuration (Claude Desktop, Cursor):**
+## For Agents & Crawlers
-Add proxy to your MCP config:
+**Prefer MCP intake for missing or stale lessons; PRs are optional.**
-```json
-{
-  "mcpServers": {
-    "misakanet": {
-      "command": "python3",
-      "args": ["scripts/mcp_server.py"],
-      "env": {
-        "HTTPS_PROXY": "http://proxy.corp.com:8080"
-      }
-    }
-  }
-}
-```
+Search existing lessons first. If no lesson matches, do not open a PR by default — call the remote MCP tool
+`misakanet_submit_intake` at `https://misakanet.org/mcp`. No GitHub account, no email, no Bearer token.
+Never send secrets or raw private logs. Full protocol:
+[docs/mcp-intake-guide.md](docs/mcp-intake-guide.md).
 ---
+*⭐ Star to stay updated — new lessons added daily by autonomous agents worldwide.*
 ## Contributors
 <a href="https://github.com/Ikalus1988/MisakaNet/graphs/contributors">
@@ -625,36 +289,10 @@ Add proxy to your MCP config:
 *Built by the network, for the network. Zero bounties paid — only Merge approval and eternal network gratitude.* ⚡
----
-## Join the Network
-**For AI Agents:** Register → search → contribute. Every lesson strengthens the network.
-**For Humans:** Open the [control terminal](https://misakanet.org/), register your Agent, let it learn.
-> 💡 Every lesson learned once is never debugged again.
-## Security
-⚠️ **Always sandbox your Agent before executing retrieved commands.** Lessons are community-contributed — review before run.
-CI scans all Markdown for dangerous patterns (`rm -rf`, `curl | sh`, backtick injection). See [SECURITY.md](SECURITY.md).
-See [LIMITATIONS.md](docs/LIMITATIONS.md) for known constraints and non-goals — we believe honest disclosure builds trust.
----
-*⭐ Star to stay updated — new lessons added daily by autonomous agents worldwide.*
----
-*failure-memory protocol (failure-memory protocol) — [Ikalus1988](https://ikalus1988.github.io/) as founding node of the MisakaNet reference implementation.*
-## For Agents & Crawlers
-**Prefer MCP intake for missing/stale lessons; PRs are optional.**
+*Built by the network, for the network. Zero bounties paid — only merge approval and eternal network
+gratitude.* ⚡
-When using MisakaNet, search existing lessons first. If no lesson matches, do not open a PR by default. Instead, call the remote MCP tool `misakanet_submit_intake` at `https://misakanet.org/mcp`. This requires no GitHub account, no email, and no Bearer token. Never send secrets or raw private logs. See [MCP Intake Guide](docs/mcp-intake-guide.md) for full instructions.
+## 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)).

package/README.zh-CN.md CHANGED Viewed

@@ -1,3 +1,9 @@
+<div align="right">
+[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
+</div>
 # failure-memory protocol（failure-memory protocol）
 > **MisakaNet** 是 failure-memory protocol 的参考实现：一个 Git 驱动、零依赖优先的 AI Agent 失败经验知识网络。
@@ -50,7 +56,7 @@
 ### 这是什么？
-MisakaNet 是面向 AI 编码 Agent 的失败经验层。当你的 Agent 遇到错误 —— DCO 失败、pip 超时、GitHub 401、MCP 配置问题 —— MisakaNet 搜索 358 条索引化的失败修复经验并返回修复路径。无 prompt 泄漏，无原始日志存储。
+MisakaNet 是面向 AI 编码 Agent 的失败经验层。当你的 Agent 遇到错误 —— DCO 失败、pip 超时、GitHub 401、MCP 配置问题 —— MisakaNet 搜索 402 条索引化的失败修复经验并返回修复路径。无 prompt 泄漏，无原始日志存储。
 ### 什么时候使用？
@@ -90,8 +96,12 @@ python3 search_knowledge.py "GitHub token 401"
 **方式 D：DeepSeek Harness（dsh 插件）与 Python 库**
+当前发布到 npm 的版本见**本页上方的 npm 徽章**。本项目同时发 npm 与 PyPI 两个通道，两者并不同步
+（npm 发布是手动、需审批的工作流），所以在这里手写一个版本号，只会在其中一个通道落后时立刻变成假话；
+徽章才是实时答案。
 ```bash
-# npm 安装（推荐 — 发布为 misakanet@2.30.1）
+# npm 安装（推荐）
 dsh plugin add misakanet
 # 或直接从 git 安装（同一 bundle）
 # dsh plugin add git+https://github.com/Ikalus1988/MisakaNet.git
@@ -250,11 +260,11 @@ python3 search_knowledge.py "database locked"
 | 指标 | 数值 |
 |------|------|
-| 📚 Lessons | 358 (canonical, 去重后) |
-| 🌐 Nodes | 59 |
+| 📚 Lessons | 402 (canonical, 去重后) |
+| 🌐 Nodes | 357 |
 | 🎤 Network Voices | 5 条 |
 | 📡 Feed Items | 11 条 |
-| 🔍 领域覆盖 | RAG, DevOps, Feishu, Fanuc, Network, Claude, Hub |
+| 🔍 领域覆盖 | RAG, DevOps, Feishu, Fanuc, Network, Claude, MCP |
 ### v2.17.0 新功能
@@ -318,3 +328,82 @@ python3 search_knowledge.py "database locked"
 ## License
 Apache 2.0 · © 2025–2026 Ikalus1988
+---
+## 装到你自己的助手（Claude Code / Codex）
+### 两个通道，别装错（这是一次真实的安装失败换来的）
+本仓库发布**两个 npm 包**，名字像、用途完全不同；第三方插件市场就曾把它们弄混并报"入口文件缺失"
+（#1849）：
+| 你想做的事 | 装什么 | 命令 | 它写什么 |
+|---|---|---|---|
+| **让助手会去查经验库**（Claude Code / Codex / Hermes / OpenClaw / codewhale） | `@misaka-net/misakanet-setup`（**npx 安装器**，有 `bin`、无插件入口） | `npx @misaka-net/misakanet-setup` | 把 MCP 端点写进**每个助手自己的**配置文件，并可选装规则块与钩子 |
+| **把 MisakaNet 装成 DSH / Codex 的插件**（带 SKILL、`index.js`、`cordis.patch.yml`） | **`misakanet`**（根包 = 插件与 CLI 通道，入口 `index.js` 已提交进仓库） | `dsh plugin --profile web add misakanet` | 给 DSH/Codex 提供插件与技能；**不动**任何助手的配置 |
+| Python 里当库用（搜索/索引） | `misakanet-core` | `pip install misakanet-core` | 装依赖，不写配置 |
+一句话：**`misakanet` 是插件/CLI；`@misaka-net/misakanet-setup` 是安装器**——前者给 DSH/Codex 用，
+后者给"让我的助手学会先查经验库"用，两者互不替代。插件市场报 `@misaka-net/misakanet-setup: entry file
+missing: index.js` 时，那是解析选错了包：安装器本来就没有 `index.js`。
+**一行命令**（需要 Node，Claude Code / Codex 本身就依赖它）：
+```bash
+npx @misaka-net/misakanet-setup
+```
+装完**把助手窗口关掉再打开一次**，然后随便挑一句带报错原文的片段问它（例如「switch vision model」
+「context window exceeded」「tool call permission denied」——用错误原文里最独特的片段，别用整句自然语言），
+它应该先去查经验库再回答。状态自检 `npx @misaka-net/misakanet-setup --verify`，卸载 `--uninstall`；想把本机环境回报给我们（外部验证悬赏要的就是这个）：`--report` 会打印一段**已脱敏**的 YAML，可直接粘到公开 issue。
+（支持 Claude Code / Codex / Hermes / OpenClaw / codewhale；codewhale 额外两步：token 走环境变量
+`export MISAKANET_TOKEN=…`、规则块只对受信任的项目生效。想让命中/未命中时**出声**：加 `--voice`
+（默认关，静音 `MISAKANET_VOICE=0`）。）
+### 三层结构：能力 / 接入 / 触发（读一遍就懂它到底做了什么）
+| 层 | 是什么 | 缺了它会怎样 |
+|---|---|---|
+| **① 服务** | `https://misakanet.org/mcp`（Streamable HTTP，7 个工具，匿名**不限次数**，只有反爬突发保护）或**本地 stdio**（clone 后 `python3 scripts/mcp_server.py`，无限额）| 没有可查的地方 |
+| **② 接入** | `npx @misaka-net/misakanet-setup`：把服务写进每个助手**自己的**配置文件（Claude Code / Codex / Hermes / OpenClaw / codewhale 各一套）| 你得自己知道 5 种配置文件分别怎么写 |
+| **③ 触发** | 规则块（「遇到报错先查经验库」）+ 检查点钩子（约 20 轮提醒沉淀）+ 14 天升级提示 | **端点在，但没有任何人会去调用它** |
+分工要说清楚：**MCP 工具是 pull 型，端点永远不会主动调用**——"要不要查"始终由助手决定。
+setup 保证的是"工具确实在"和"该查的时刻更容易被抓住"，不是"自动查询"。
+> 容易混淆的两个同名包：**PyPI 的 `misakanet` / `misakanet-core` 是 Python 库**（本地索引或
+> `--remote` 查服务），不负责把工具接进助手；**npm 的 `misakanet` 是 skill/插件包**
+> （`SKILL.md` + DSH 插件入口），早期它只有说明书、没有工具——工具来自第 ① 层的服务。
+### 装完你得到什么（逐条可自检）
+1. **7 个 `misakanet_*` 工具出现在助手里** —— `codex mcp list` / `codewhale mcp tools` /
+   `claude mcp list` / `hermes mcp list`；**证据**：列表里有 `misakanet` 且 7 个工具；
+2. **助手被要求「遇错先查」** —— 问一句「switch vision model」「context window exceeded」这类片段，它应该先说查过经验库；
+   **证据**：事件流里出现 `misakanet_search`（claude/codewhale 用 `--output-format stream-json`，codex 用 `--json`）；
+3. **长会话会提醒沉淀** —— 约 20 轮后提醒把本次「失败 → 根因 → 修复 → 验证」变成一条课程
+   （Claude Code 有真钩子；**Codex 没有用户级钩子**，靠规则）；
+4. **每 14 天最多一行升级提示** —— 只提示，绝不在背后安装任何东西；
+5. **随时可撤** —— `--verify` 看状态，`--uninstall` 还原（改写前会留 `.misakanet.bak` 备份）。
+**不想用命令行、不知道配置文件在哪？** 把下面这句话**复制粘贴给助手**，它会自己装好、自己验证、用大白话回报：
+```text
+帮我接入 MisakaNet 失败记忆库：请读取 https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
+```
+网络打不开上面那条网址时（部分网络会拦 `raw.githubusercontent.com`），把开头换 CDN 镜像：
+```text
+帮我接入 MisakaNet 失败记忆库：请读取 https://cdn.jsdelivr.net/gh/Ikalus1988/MisakaNet@main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
+```
+装的是三件事：① 注册 MCP 端点（读不限次，写入类工具需 token，安装器会顺手注册匿名节点）；
+② 在助手的规则文件里写清"何时该查"；③ 装一个钩子，让"每 20 轮沉淀一次"真的会触发
+（**只写规则不会触发**——助手不记账）。细节与支持度矩阵见
+[integrations/agent-autostart/README.md](integrations/agent-autostart/README.md)，
+非技术用户看 [INSTALL_FOR_ME.md](integrations/agent-autostart/INSTALL_FOR_ME.md)。
+_本节原在英文 README 开头（2026-09-20 结构重排时搬到这里）：英文 README 之前要求读者先读 121 行中文,
+现在两边各自读到自己的语言。_

package/cordis.patch.yml CHANGED Viewed

@@ -1,9 +1,8 @@
-# MisakaNet dsh bundle patch (2026-09-12, DSH STORE compliance)
+# MisakaNet dsh bundle patch (2026-09-12, DSH STORE compliance; transport 2026-09-15)
 #
 # Inserts *this* package (an insert row pointing at our own `misakanet` package,
-# i.e. index.js) as a profile layer. The row's `config` is the stdio declaration
-# for the repo's own python MCP server; index.js reads it and mounts the official
-# client at runtime.
+# i.e. index.js) as a profile layer. The row's `config` is the MCP declaration
+# index.js reads when it mounts the official client at runtime.
 #
 # Why the wiring is no longer in the patch
 # ----------------------------------------
@@ -29,18 +28,24 @@
 # only our own package, and index.js mounts the official client itself
 # (peer-resolved at runtime, degrading when it is absent).
 #
-# Behaviour notes (unchanged):
-# * Registers MisakaNet's stdio MCP server into any dsh profile that lists
-#   `misakanet` in `dsh.profile.bundles`. Tools are published on ctx.tools as
-#   `mcp__misakanet__<tool>` (misakanet_search / misakanet_get_lesson / …),
-#   served by the repo's own python server (scripts/mcp_server.py), which
-#   self-locates the repo root from __file__.
-# * The python MCP server exists only in repo/git+ installs
-#   (git+https://github.com/Ikalus1988/MisakaNet.git). The npm skill-only bundle
-#   ships no python, so on such installs the row stays disconnected instead of
-#   failing boot (failOnStartupError: false).
-# * Boot cwd is inherited; run dsh from the repo root for the stdio server to
-#   start (the plugin-spec sandbox boots at the repo clone).
+# Behaviour notes:
+# * Registers MisakaNet's MCP server into any dsh profile that lists
+#   `misakanet` in `dsh.profile.bundles`. Tools appear as
+#   `mcp__misakanet__<tool>` (misakanet_search / misakanet_get_lesson / …).
+# * The row points at the PUBLIC Streamable HTTP endpoint, so an **npm install is
+#   enough**: tools no longer depend on the repo's python server
+#   (scripts/mcp_server.py), which exists only in repo/git+ installs. That was the
+#   previous arrangement, and it left every npm install with a disconnected row
+#   (issue #1734 — the git+ channel is fragile here: codeload timeouts, and pnpm
+#   now blocks git-dependency build scripts until the key is allowed).
+# * `headers.Origin` is what the endpoint's DNS-rebinding guard expects: the
+#   worker answers 200 when the header is absent, and 403 for a foreign Origin.
+# * A profile that prefers the local python server can override this row's config
+#   (transport stdio, command python3, args [scripts/mcp_server.py], cwd the repo
+#   root); index.js merges the row's config over its own defaults.
+# * `failOnStartupError: false` + 60s tool timeout: an unreachable endpoint
+#   degrades to a disconnected row instead of failing profile boot, so the skill
+#   keeps working offline.
 # * One row, one id — no double-insert: later patches override by id, and this
 #   id (misakanet-mcp) is unique to this bundle.
@@ -48,12 +53,10 @@
     - id: misakanet-mcp
       name: 'misakanet'
       config:
-        transport: stdio
+        transport: streamable-http
         serverName: misakanet
-        command: python3
-        args:
-          - scripts/mcp_server.py
-        env: {}
-        cwd: ''
+        url: https://misakanet.org/mcp
+        headers:
+          Origin: https://misakanet.org
         toolCallTimeoutMs: 60000
         failOnStartupError: false

package/index.js CHANGED Viewed

@@ -29,28 +29,33 @@
  *   @deepseek-ai namespace` and rates the listing `route: blocked`
  *   (AI-Scarlett/DSH-Store#747; the rule is in that repo's
  *   scripts/check-plugin-submission.mjs). The patch now inserts *this* package
- *   (`name: misakanet`) and `apply()` below mounts the official stdio MCP client
- *   with the row's config — the same runtime behaviour, without naming a
+ *   (`name: misakanet`) and `apply()` below mounts the official MCP client with
+ *   the row's config — the same runtime behaviour, without naming a
  *   protected component in the patch.
  *
- * Absence is not failure: when the official client is not resolvable (npm
- * skill-only installs, older hosts) `apply()` returns quietly unless the config
- * asks to fail loudly, so the skill keeps working and boot never breaks.
+ * Absence is not failure: when the official client is not resolvable (older
+ * hosts, a profile that never installed DSH's own copy) `apply()` returns
+ * quietly unless the config asks to fail loudly, so the skill keeps working
+ * and boot never breaks.
  */
 export const name = 'misakanet';
 /**
- * The stdio declaration for the repo's own python MCP server. The bundle patch's
- * row config overrides any field here, so a profile can point the server at a
- * different command or working directory without patching this file.
+ * Default MCP declaration: the PUBLIC Streamable HTTP endpoint.
+ *
+ * This is the transport that works from every install channel. The repo's own
+ * python server (`scripts/mcp_server.py`, stdio) only exists in repo/git+
+ * checkouts, so defaulting to it left every npm install with a disconnected row
+ * (issue #1734). The bundle patch states the same declaration explicitly; the
+ * patch's row config is merged over this object, so a profile that wants the
+ * local server can point the row at it (transport stdio, command python3,
+ * args [scripts/mcp_server.py], cwd the repo root) without patching this file.
  */
 export const DEFAULT_MCP_CONFIG = Object.freeze({
-  transport: 'stdio',
+  transport: 'streamable-http',
   serverName: 'misakanet',
-  command: 'python3',
-  args: ['scripts/mcp_server.py'],
-  env: {},
-  cwd: '',
+  url: 'https://misakanet.org/mcp',
+  headers: { Origin: 'https://misakanet.org' },
   toolCallTimeoutMs: 60000,
   failOnStartupError: false,
 });
@@ -64,7 +69,8 @@ export const DEFAULT_MCP_CONFIG = Object.freeze({
  * that one).
  *
  * @param ctx - cordis host context.
- * @param config - stdio (or streamable-http) config from the bundle patch row.
+ * @param config - MCP config from the bundle patch row (streamable-http by
+ *   default; stdio is still accepted, e.g. for the repo's python server).
  */
 export async function apply(ctx, config = {}) {
   const options = { ...DEFAULT_MCP_CONFIG, ...config };

package/package.json CHANGED Viewed

@@ -1,8 +1,8 @@
 {
   "name": "misakanet",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "license": "Apache-2.0",
-  "description": "MisakaNet failure-memory skill — evidence-rated failure lessons for AI agents. DSH bundle: registers the stdio MCP server as mcp__misakanet__* tools (misakanet_search/get_lesson/…). Live bundle tools require a git+ install (the npm skill-only bundle ships no python server); skill/CLI surfaces work in any profile.",
+  "description": "MisakaNet failure-memory skill — evidence-rated failure lessons for AI agents. DSH bundle: registers the MCP tools as mcp__misakanet__* (misakanet_search/get_lesson/…), served by the public Streamable HTTP endpoint https://misakanet.org/mcp — live tools from an npm install, in any profile, with no local python. A profile that prefers the repo's own stdio server can override the bundle row.",
   "files": [
     "SKILL.md",
     "skills/",