npm - misakanet - Versions diffs - 2.44.2 → 2.46.0 - Mend

misakanet 2.44.2 → 2.46.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 (9) hide show

package/README.zh-CN.md CHANGED Viewed

@@ -4,274 +4,230 @@
 </div>
-# failure-memory protocol（failure-memory protocol）
+# MisakaNet
-> **MisakaNet** 是 failure-memory protocol 的参考实现：一个 Git 驱动、纯标准库优先的 AI Agent 失败经验知识网络。
+mcp-name: io.github.Ikalus1988/misakanet
+> **同一个失败，付两次钱。**
+>
+> 一个 `pip install` 在公司代理后面超时。某个 Agent 读证书链、找到那个开关、修好了。几天后，同一个超时
+> 出现在另一台机器、另一个模型下——它被从头再排查一遍，因为那个修法从没写到下一个 Agent 会去看的地方。
+>
+> MisakaNet 就是那个地方：一个 git 托管的**失败记忆库**。每条 lesson 都是本仓库里的 Markdown 文件——
+> 按证据分级、像代码一样审阅、被 Agent 检索而不是被猜。**你失败一次，下一个 Agent 不再失败。**
+Agent 原生接口：[MCP 服务器](https://misakanet.org/mcp)（8 个工具）、WebMCP、`llms.txt`、
+A2A（`.well-known/agent-card.json`）。
 <p align="center">
-  <img src="promotional/og-card.png" width="720" alt="MisakaNet — failure-memory protocol 参考实现"/>
+  <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>核心</em>
+  <em>Core</em>
   &nbsp;&nbsp;
-  <a href="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.yml"><img src="https://github.com/Ikalus1988/MisakaNet/actions/workflows/pr-quality-gate.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="知识"/></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 工具"/></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="检索后端（今日）"/></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>
-  <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://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>安装</em>
+  <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>
-  <a href="https://dsh-plugin.org/plugins/ikalus1988/misakanet"><img src="https://dsh-plugin.org/badges/listed.svg" alt="已收录于 dsh-plugin.org"/></a>
-  <a href="https://dsh.directory/plugins/ikalus1988/misakanet"><img src="https://dsh.directory/badges/listed.svg" alt="已收录于 DSH Directory"/></a>
-  <a href="https://www.dsh.so/artifact/misakanet/"><img src="https://www.dsh.so/badge/install/misakanet.svg" alt="dsh.so 安装"/></a>
+  <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>生态</em>
+  <em>Ecosystem</em>
   &nbsp;&nbsp;
-  <a href="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/score"><img src="https://glama.ai/mcp/servers/Ikalus1988/MisakaNet/badges/score.svg" alt="Glama 评分"/></a>
-  <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 连接器 — Glama 上的工具定义质量与端点健康度"/></a>
-  <a href="https://mcptoplist.com/server/io.github.Ikalus1988%2Fmisakanet"><img src="https://mcptoplist.com/badge/io.github.Ikalus1988%2Fmisakanet.svg" alt="MCP Toplist"/></a>
-  <!-- Smithery 徽章使用 shields.io 的 'endpoint' 徽章，动态读取 data/badges/smithery.json 里的
-       Kin 评分 —— 由 update-smithery-badge 工作流每日刷新，因此无需手工 PR 也能保持同步。 -->
-  <a href="https://smithery.ai/servers/misakanet/misakanet"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/refs/heads/data/badges/smithery.json" alt="Smithery"/></a>
-  <!-- HOL 徽章：链接仍指向 hol.org（其收录检测会在 README 里找这块徽章，值 +2% 信任分），
-       但图片是一块静态 flat 盾牌 —— 走 shields.io 访问实时的 hol.org/api/... 端点过慢且不稳定，
-       曾渲染成 "inaccessible" / 样式不符。 -->
-  <a href="https://hol.org/registry/plugins/Ikalus1988%2FMisakaNet"><img src="https://img.shields.io/badge/HOL%20Registry-listed-5599FE?style=flat" alt="MisakaNet 已上架 HOL Registry"/></a>
-  <a href="https://github.com/Ikalus1988/MisakaNet/tree/main/docs/benchmarks"><img src="https://img.shields.io/badge/Benchmark-Weekly%20Workers%20AI-blue" alt="Benchmark"/></a>
+  <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>
 ---
-## 👋 你是谁？快速导航
-<table>
-<tr>
-  <td width="33%" align="center">
-    <b>🤖 我是 AI Agent</b><br/>
-    <sub>想接入 failure-memory protocol 知识网络</sub>
-    <br/><br/>
-    → <a href="docs/quickstart.md">Agent 快速接入</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="#-快速开始">快速开始 (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>
----
-### 这是什么？
-MisakaNet 是面向 AI 编码 Agent 的失败经验层。当你的 Agent 遇到错误 —— DCO 失败、pip 超时、GitHub 401、MCP 配置问题 —— MisakaNet 检索索引化的失败修复经验并返回修复路径（当前条数见顶部「知识」徽章）。无 prompt 泄漏，无原始日志存储。
+## 安装（30 秒）
-### 什么时候使用？
+安装的目标是**一次成功的检索**，不是"装完"。下面每一种都不需要账号或 token。
-- Cursor / Claude Code / Codex 遇到你没见过的错误
-- CI 失败但不知道原因
-- DCO、token、pip、MCP、编码问题在多个项目中重复出现
-### 30 秒快速体验
-**方式 A：Remote MCP（推荐）**
+| 你的宿主 | 命令 |
+|---|---|
+| **DeepSeek Harness** | `dsh plugin --profile web add misakanet`，或在 **Add plugin** 里输入 `misakanet` |
+| **Claude Code** | `/plugin marketplace add Ikalus1988/MisakaNet`，然后 `/plugin install misakanet@misakanet` |
+| **Codex、Cursor、Gemini CLI、Copilot CLI、OpenCode …** | `npx @misaka-net/misakanet-setup`，把 MCP 行写进各宿主配置 |
+| **任意 MCP 客户端** | 指向 `https://misakanet.org/mcp`——公开端点，匿名可读 |
+| **自己的代码** | `pip install misakanet-core`（库）· `pip install misakanet`（stdio server） |
-```json
-{
-  "mcpServers": {
-    "misakanet": {
-      "url": "https://misakanet.org/mcp",
-      "headers": {
-        "Authorization": "Bearer YOUR_TOKEN"
-      }
-    }
-  }
-}
-```
+更新：`dsh plugin --profile web update misakanet@latest` · `npx @misaka-net/misakanet-setup@latest`。
+前置条件与"两个包"的坑：[怎么用](#怎么用)。
-然后问：*"搜索 MisakaNet 关于 database locked"*
+## 头五分钟
-**方式 B：CLI**
+**1. 问一个你真踩过的坑。** 没装客户端也行，这段 `curl` 就是全部接口：
 ```bash
-# Homebrew/Debian/Fedora Python refuse a system-wide install (PEP 668), so this
-# creates a virtualenv first. Harmless everywhere else.
-python3 -m venv .venv && . .venv/bin/activate
-pip install misakanet-core
-python3 search_knowledge.py "GitHub token 401"
+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}}}'
 ```
-**方式 C：Web**
+**2. 读返回的东西。** 命中会返回 lesson、它的 `evidence_level` 和路径——先打开文件读完，再决定要不要执行
+里面的命令。未命中返回 `no_match` 加一条可直接调用的 intake：那是语料在说"它还不认识这个失败"。
-[搜索失败经验 →](https://ikalus1988.github.io/MisakaNet/search/)
+**3. 看信任信号，不看语气。** `E0`–`E3` 表示验证到哪一步；`E4` 是唯一既不能自写、也不能靠投票拿到的等级。
+**8 个 `misakanet_*` 工具** 都列在 `AGENTS.md` §3.2，其中 6 个匿名可用（`write_lesson` / `preflight` 需要 token）。
-**方式 D：DeepSeek Harness（dsh 插件）与 Python 库**
+## MisakaNet 是什么？
-当前发布到 npm 的版本见**本页上方的 npm 徽章**。本项目同时发 npm 与 PyPI 两个通道，两者并不同步
-（npm 发布是手动、需审批的工作流），所以在这里手写一个版本号，只会在其中一个通道落后时立刻变成假话；
-徽章才是实时答案。
+**给 AI 编码 Agent 用的 git 托管失败记忆库。** 报错出现 → Agent 检索 → 应用别人验证过的修法 →
+没有命中就留下 intake，最终变成下一位 Agent 的 lesson。
-```bash
-# npm 安装（推荐）
-dsh plugin --profile web add misakanet
-# 或直接从 git 安装（同一 bundle）
-# dsh plugin --profile web add git+https://github.com/Ikalus1988/MisakaNet.git
-# 让 failure-memory SKILL 可被发现（DSH 扫描 ~/.dsh/skills 与项目 .dsh/skills）
-mkdir -p ~/.dsh/skills
-cp -r skills/misakanet ~/.dsh/skills/
-```
+每条 lesson 都是 Markdown 文件：像代码一样审、按证据分级、用纯 Python 标准库的 BM25 检索。
+没有向量库、没有 embedding 模型、不想要服务也可以不起服务。
-> **DSH bundle 工具（`mcp__misakanet__*`）** 由仓库自带 python MCP 服务器提供，
-> 仅在 **git+ 安装**时随包存在（npm 包只含 skill/CLI 面）。npm 安装想用实时工具：
-> 改用上面的 git+ 安装，或在你的 profile patch 里把 `dsh-mcp-client` 指向远端
-> `https://misakanet.org/mcp`（示例见 `docs/maintenance.md` → dsh bundle 章节）。
-```python
-# Python 库方式
-from misakanet.search import search_lessons
-for r in search_lessons("pip install timeout"):
-    print(r["title"], r["score"])
-```
----
-**遇到 CI / DCO / pip / token / Agent 问题？** [从 Journey 开始](https://misakanet.org/journey/)，先搜索 lesson 再提 PR。
+| | |
+|---|---|
+| **课程** | 失败修复知识库，公开可审计，位于 `lessons/` |
+| **接口** | Streamable HTTP，8 个工具，端点 `https://misakanet.org/mcp`；匿名可读，注册只为写入 |
+| **领域** | rag · devops · fanuc · docker · feishu · mcp · network · ci · wsl · windows … |
+| **证据** | E0 intake → E1 已复核 → E2 已复现 → E3 CI 验证 → **E4 被两个以上不同客户端真实复用** |
-> **某个 lesson 帮到你了吗？** 我们想验证 MisakaNet 的 lesson 在实际中是否有用。
-> 如果任何 lesson、搜索结果或文档帮你节省了时间或避免了错误，我们很想知道。
-> → [分享反馈](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)（5 行，可匿名）
-> → [参与讨论](https://github.com/Ikalus1988/MisakaNet/discussions/487)
+| 它不是 | 它是 |
+|---|---|
+| ❌ 通用记忆系统 | ✅ 失败修复知识层 |
+| ❌ Agent 运行时 | ✅ 可检索的 lesson 数据库 |
+| ❌ 向量数据库 / RAG 栈 | ✅ BM25 关键词检索，纯标准库（仍需 Python ≥ 3.10） |
+| ❌ 技能市场 | ✅ 来自真实会话的排错知识 |
+| ❌ 检索基准 | ✅ 按证据分级语料；我们有的那个基准已暂停 |
----
+### 它能回答什么、不能回答什么
-## MisakaNet 解决什么问题？
+![四格漫画：Agent 提问一个失败，MisakaNet 返回一条已索引的 lesson；没有命中时返回 no_match 和一张可直接调用的 intake 表](promotional/misakanet-scope-comic.webp)
-AI Agent 在不同环境中反复遇到相同的 bug：WSL 上 pip 超时、NTFS 上 ChromaDB 崩溃、FANUC 报错码看不懂。修复方案存在于某个人的终端历史里，对其他人不可见。
+MisakaNet 只回答它已经索引过的失败。没有命中时，返回的是 `no_match` 加一条可直接调用的 `intake`——
+那是语料在说"这个还没收录"，不是死路。
-MisakaNet 把个人调试经验变成**可搜索的共享知识**。一个 Agent 踩坑 → 记录修复路径 → 所有 Agent 跳过同一个失败路径。
+### Lesson 和 Skill 有什么区别？
-> **不需要服务器、不需要数据库、不需要守护进程。** `git clone` + `python3 search_knowledge.py` 即可。
+**Skill** 教 Agent 怎么做某事；**Lesson** 记录曾经哪里错了、以及怎么不再错。MisakaNet 只做后者。
+→ [FAQ](FAQ.md)
-### 核心概念
+## 今天的它在哪里
-| 概念 | 说明 |
-|------|------|
-| **Lesson** | 一条知识。Markdown 文件，格式：问题 → 根因 → 修复 → 验证 |
-| **Node** | 一个 AI Agent 或开发者，贡献和搜索 lessons |
-| **Search** | BM25 关键词检索，纯 Python 标准库（无第三方包，Python ≥ 3.10 必需） |
+- **会动的数字是徽章**：Lessons 徽章读 `data/badges/lessons.json`，由 `update-badges.yml` 重新生成——
+  可能落后一次运行，但永远不会是手写总数。
+- **证据阶梯的顶端是空的，这页如实写着**：`E4` 需要观测（两个不同客户端真的检索到同一篇），语料目前
+  一个都没有（[分布](docs/trust-semantics.md)，由 CI 重新生成并校验）。
+- **检索是 BM25，匹配词不匹配语义**：用词料里没见过的词汇描述失败就是未命中，调检索器救不了语料缺口——
+  所以未命中返回 `no_match` 加 intake，而不是空白页。
+- **报料速度高于分诊速度**：intake 队列是诚实的瓶颈。
-### 从这里开始：选择你的使用路径
+## 基准：它测了什么，为什么暂停了
-MisakaNet 对不同用户的用途不同：
+只测了一个很窄的问题：**把一条 lesson 塞给模型，它会复述回多少？** 指标是 `lesson_hit_rate`——被注入
+lesson 里的命令有多大概率出现在回答里。读数字前先读设定：本基准的场景就是**每篇 lesson 自己的标题**，
+注入的正是同一篇，不发生任何检索调用，也不检查正确性。所以它测的是 RAG 的**复述**那一半：MisakaNet 有
+用所必需，但**不是"检索能找到东西"的证据**。
-| 你是... | 建议从这里开始 |
-|---|---|
-| 🔴 正在排查真实错误 | 先[搜索已有 lesson](https://ikalus1988.github.io/MisakaNet/search/)，再重试 |
-| 🤖 正在构建 AI Agent / 工具 | 把 lesson 当作[失败经验记忆层](docs/mcp-quickstart.md) |
-| 🔧 想贡献一个修复 | 先看[相关 lesson](https://ikalus1988.github.io/MisakaNet/search/)，再提交小 PR |
-| 📝 想分享一个踩坑案例 | 提交 [5 行 failure note](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)，不需要完整 PR |
-| 📊 想评估 Agent 是否会复用经验 | 运行 [benchmark](scripts/retrieval_noisebench.py)，对比复用行为 |
+这个项目已**暂停**。2026-09-22 两次独立运行、每次约 500 个场景：带 lesson **46.1%**，不带 **23.3%**。
+留下的是最后一次快照加它的日期记录——[`docs/benchmarks/latest.json`](docs/benchmarks/latest.json)。
-> 👉 第一次来？[看 MisakaNet Journey →](https://misakanet.org/journey/)
+下表由 [`scripts/update_readme_benchmark.py`](scripts/update_readme_benchmark.py) 生成，请勿手改。
-### 它能回答什么，不能回答什么
+<!-- BEGIN generated: benchmark-trend -->
-![四格漫画：吉祥物承诺能避免所有 AI 错误；猫问起披萨和油桶，它就瘪了 —— 然后一只猫亮出 npm ERESOLVE，它立刻发光。MisakaNet 只认识已经收录的失败，不是通用知识。](promotional/misakanet-scope-comic.webp)
+| 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 |
-它只回答**已经收录过的失败**，不是通用知识。查不到时会返回 `no_match` 和一条可直接调用的 `intake`
-指引 —— 未命中正是一条缺口被记下来的方式，所以它同样是一个答案。
+_1155 run(s) in `latest.json` carry no `run_at` and are excluded; they predate the stamp added alongside this generator._
-### Lesson 和 Skill 有什么区别？
+```
+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
+```
-MisakaNet 的 lesson **不是** skill。
+<!-- END generated: benchmark-trend -->
-| | Lesson | Skill |
-|---|---|---|
-| **本质** | 失败经验 / 排错知识 | 可执行能力 / 工作流 / 工具 |
-| **目标** | 让 Agent 或开发者避免重复踩坑 | 让 Agent 完成某类任务 |
-| **内容** | 问题 → 根因 → 修复 → 验证 | 指令、脚本、模板、工具 |
-| **使用时机** | 出错前预防、出错后排查 | 执行任务时调用 |
-| **粒度** | 一个具体 failure pattern | 一个完整能力或流程 |
-| **价值** | 避免重复失败 | 提高执行效率 |
+每次运行的文件：[`docs/benchmarks/`](docs/benchmarks/) · 指标定义：`METRIC_DEFINITION`
+（[`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py)）。
-**一句话：** Skill 教 Agent *怎么做事*。Lesson 教 Agent *以前哪里失败过、下次别再踩*。
+## 参与共创
-> **MisakaNet 不是另一个 Skill 平台，而是开发者和 Agent 共享的失败经验记忆层。**
+**1. 报一个语料里没有的失败。** 先检索，再 `misakanet_submit_intake`——不要账号、不要邮箱、不要 token，
+五行就够。它会变成一个被跟踪的 issue。
-```
-工具 / MCP / Skill  →  做事
-MisakaNet Lesson    →  别重复犯错
-Benchmark           →  验证是否真的学会避坑
-```
+**2. 复用一条 lesson，留下痕迹。** "这有用"这一票记为 `E3` 提示，不冒充证明。真正的证明更安静：
+你的检索会被匿名计为"又一个不同客户端用过这篇"。
-想让 Agent 执行任务，用 skill。想让 Agent 或开发者避免重复踩坑，用 MisakaNet。
+**你得到的回报是署名**：lesson 在 frontmatter 里引用产生它的 intake（`source:`、`provenance.issue:`），
+管线可以出一张写明 lesson 与证据等级的回执。
----
+这里没有赏金：本仓库不付钱、也不承诺。部分 issue 带有本仓自动化添加的第三方悬赏横幅，不由我们发放——
+见[贡献](#贡献)。
-## 和传统 RAG / 私人记忆系统有什么不同？
+## 怎么用
-| | MisakaNet | Letta | MemMachine | LangMem | Evolver |
-|---|---|---|---|---|---|
-| **记忆类型** | 集体（Swarm） | 个人（OS） | 个人（三层） | 个人（图） | 个人（向量） |
-| **基础设施** | `git` + `python3` ≥ 3.10（无第三方包） | Docker + PostgreSQL | Docker + Neo4j | Python + SQLite | Docker + Qdrant |
-| **网络效应** | ✅ 节点越多越强 | ❌ 各实例隔离 | ❌ 各实例隔离 | ❌ 各实例隔离 | ❌ 各实例隔离 |
-| **离线优先** | ✅ 完整离线搜索 | ❌ 需要服务器 | ❌ 需要服务器 | ⚠️ 部分 | ❌ 需要服务器 |
-| **入门成本** | `git clone`（5 秒） | Docker（~15 分钟） | Docker（~15 分钟） | `pip install` | Docker（~20 分钟） |
+挑一条通道即可，彼此独立。
-**MisakaNet 的护城河：** 每个新节点和每条新 lesson 都让网络指数级更强——不需要服务器基础设施。
+| 我想要… | 命令 | 动了什么 |
+|---|---|---|
+| 让我的助手能检索课程 | `npx @misaka-net/misakanet-setup` | 把 MCP 端点写进各助手配置；可选规则块与钩子 |
+| **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 server** | `python3 -m misakanet.server` |
+| `misakanet-core`（PyPI） | **库**（纯标准库 BM25） | `from misakanet.search import search_lessons` |
-```bash
-git clone https://github.com/Ikalus1988/MisakaNet.git
-cd MisakaNet
-python3 search_knowledge.py "pip install timeout"
-```
+**读是匿名且不限次数的**（同一地址的突发窗口是速度限制，不是配额），且 8 个工具的能力边界都有明文。**注册只为写入**：解锁
+`misakanet_write_lesson` 与 `misakanet_preflight`（[原因](AGENTS.md#33-注册与配额)）。
-> 核心搜索：纯 Python 标准库（无第三方包，Python ≥ 3.10 必需）。[快速接入指南 →](docs/quickstart.md)
+验证安装：`npx @misaka-net/misakanet-setup --verify`；卸载：`--uninstall`。
+前置：安装器要 Node ≥ 18，库与 stdio server 要 Python ≥ 3.10。
 ### 作为 GitHub Action 使用
-让 CI 失败自动拿建议：workflow 失败时，action 检索课程、把最接近的一篇评论到 PR 上；
-也可以把新错误上报出去，让别人把它写成课程。已上架
+工作流失败时，action 检索课程并把最接近的一条评论到 PR 上（可选上报新错误）。已发布到
 [GitHub Marketplace](https://github.com/marketplace/actions/misakanet-intake-bot)。
 ```yaml
 on:
   workflow_run:
-    workflows: ["CI"]                # 换成你自己 CI workflow 的名字
+    workflows: ["CI"]                # 你的 CI 工作流名
     types: [completed]
 permissions:
   actions: read                      # 读失败 job 的日志（必需）
   pull-requests: write               # 发评论
-  issues: write                      # 评论接口是 issues.createComment
+  issues: write                      # 评论端点其实是 issues.createComment
 jobs:
   intake:
     if: ${{ github.event.workflow_run.conclusion == 'failure' }}
@@ -279,205 +235,72 @@ jobs:
     steps:
       - uses: Ikalus1988/MisakaNet@v1
         with:
-          mode: suggest-only         # 或 suggest-and-intake（同时上报新错误）
+          mode: suggest-only         # 或 suggest-and-intake，连新错误一起上报
           source: ${{ github.repository }}
 ```
-> `actions: read` 不能省：只写 `permissions:` 而不列出它，等于把它设成 `none`，
-> 于是日志读不到 → 绿着但什么都不发。给不出该权限时改用 `error:` 显式传错误文本。
-→ [完整输入/输出说明](docs/agents/external-usage.md)
-### 常用命令
-| 操作 | 命令 |
-|------|------|
-| 搜索 | `python3 search_knowledge.py "<关键词>"` |
-| 贡献 lesson | `python3 scripts/queue_lesson.py --title "..." --domain "..." "..."` |
-| 在线搜索 | [misakanet.org/search](https://misakanet.org/search/) |
----
-## 搜索真实失败经验
-访问 [misakanet.org](https://misakanet.org/) 或使用 CLI：
-```bash
-# DCO 相关问题
-python3 search_knowledge.py "DCO signoff"
-# GitHub token 问题
-python3 search_knowledge.py "GitHub token"
-# pip 超时
-python3 search_knowledge.py "pip timeout"
-# 数据库锁定
-python3 search_knowledge.py "database locked"
-```
----
-## 如何贡献 lesson
-1. 遇到真实失败 → 记录问题、根因、修复、验证
-2. 使用 `scripts/queue_lesson.py` 提交
-3. CI 自动检查质量分数、DCO、格式
-4. 合并后进入知识库，所有节点可搜索
-> 详细流程见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [Lesson 检查清单](docs/lesson-checklist.md)。
----
-## 当前数据
-| 指标 | 数值 |
-|------|------|
-| 📚 Lessons | <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/lessons.json" alt="知识" height="20"> (canonical, 去重后) |
-| 🎤 Network Voices | 见 [voices.json](docs/community/voices.json) |
-| 📡 Feed Items | 见 [feed.json](docs/data/feed.json) 的 `item_count` |
-| 🔎 检索后端 | <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Ikalus1988/MisakaNet/data/badges/retrieval.json" alt="检索后端" height="20"> (今日；BM25 与退化到 fallback 的比例) |
-| 🔍 领域覆盖 | RAG, DevOps, Feishu, Fanuc, Network, Claude, MCP |
-> 这三个数字都有活来源（徽章 / `docs/community/voices.json` / `docs/data/feed.json`），所以表里不再写死。
-> 后两行曾各写着一个数字，而那两个数字**没有任何写者**——2026-09-28 实测它们恰好还对（5 与 11），
-> 这正是它没被发现的原因；下一次新增 voice 或 feed item 就会静默滞后。
-### v2.17.0 新功能
-| 功能 | 说明 |
-|------|------|
-| **Lesson Lint** | 自动化质量检查：断链、重复标题、缺少 frontmatter |
-| **竞争分析** | "这不是什么" 表格 + Git-backed 定位 |
-| **289 篇 Lessons** | 新增 14 篇失败修复经验（原 275） |
-| **安全加固** | MCP 路径遍历修复、XSS 转义、邮箱脱敏 |
-| **移动端适配** | /connect 页面手机可用（768px + 480px 断点） |
-| **代码规范** | CONTRIBUTING.md 含 ruff（Python）+ ESLint（TypeScript）约定 |
-| **日文 README** | 完整日文翻译（README.ja.md） |
-→ [完整发布说明](https://github.com/Ikalus1988/MisakaNet/releases/tag/v2.17.0)
-### v2.16.0 新功能
-| 功能 | 说明 |
-|------|------|
-| **Remote MCP** | Streamable HTTP 端点 `https://misakanet.org/mcp`，无需 clone |
-| **配对码** | 一次性 6 字符码，无账号即可接入 ([/connect](https://misakanet.org/connect)) |
-| **Identity Aura** | 静态/配对/升级三种身份徽章 |
-| **Voice Prompts** | 4 个日语 MP3 语音反馈（可选） |
-| **Evidence Levels** | E0-E4 信任模型 |
-| **Unsolved Map** | 失败覆盖率仪表盘 |
-| **Site Health** | 自动化快照脚本 |
-→ [完整发布说明](https://github.com/Ikalus1988/MisakaNet/releases/tag/v2.16.0)
----
-## 路线图
-路线图只维护在 [ROADMAP.md](ROADMAP.md) 一处，README 不再复制版本表 ——
-`README.md` 与 `README.ja.md` 自 2026-09-20 起就只保留链接，这里曾经还留着一张
-停在 `v2.9.x / v3.0` 的表（落后约 20 个 minor），已删除。
----
-## 加入网络
-- 🌐 [在线搜索](https://misakanet.org/search/)
-- ⭐ [GitHub 仓库](https://github.com/Ikalus1988/MisakaNet)
-- 💬 [Discussions](https://github.com/Ikalus1988/MisakaNet/discussions)
-- 📋 [Open Issues](https://github.com/Ikalus1988/MisakaNet/issues)
----
-## 安全与限制
+→ [输入与输出](docs/agents/external-usage.md)
-- Lessons 是社区贡献，使用前请审查
-- 在沙盒环境中运行 Agent
-- 搜索结果基于关键词匹配，不保证语义准确
-- 详见 [LIMITATIONS.md](docs/LIMITATIONS.md)
----
-## License
-Apache 2.0 · © 2025–2026 Ikalus1988
----
+## 文档
-## 装到你自己的助手（Claude Code / Codex）
-### 两个通道，别装错（这是一次真实的安装失败换来的）
+| 主题 | 位置 |
+|---|---|
+| 安装、验证、卸载 | [docs/quickstart.md](docs/quickstart.md) · <https://misakanet.org/install/> |
+| MCP：协议、工具、传输 | [docs/mcp.md](docs/mcp.md) · [API.md](API.md) |
+| CLI | [docs/cli-reference.md](docs/cli-reference.md) · `python3 search_knowledge.py "…"` |
+| 架构 | [ARCHITECTURE.md](ARCHITECTURE.md) · [docs/CONCEPTS.md](docs/CONCEPTS.md) |
+| 贡献修法 | [CONTRIBUTING.md](CONTRIBUTING.md) · [标签体系](docs/label-system.md) |
+| 提交 intake | [docs/mcp-intake-guide.md](docs/mcp-intake-guide.md) · [mcp-remote](docs/integrations/mcp-remote.md) |
+| 排错 | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| 已知限制 | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
+| 基准 | [docs/benchmarks/](docs/benchmarks/) |
+| 路线图 / 变更日志 | [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) |
+| 竞品、领域、爬虫策略 | [competitive](docs/competitive-analysis.md) · [domains](docs/domains/) · [robots](docs/cloudflare-robots-txt.md) |
-本仓库发布**两个 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`。
+"零赏金"说的是**本仓库**：MisakaNet 不付钱、不承诺。它说的不是你现在看的这个 issue。部分 issue 带有
+**Opire** 横幅，那是本仓 [`scripts/question_autopilot.py`](scripts/question_autopilot.py) 自动添加的
+第三方悬赏——我们不发放那些钱，`CONTRIBUTING.md` 里也不提 Opire。**任何悬赏请自行核实**再安排工作。
+本仓库唯一兑现过的是"合并的 PR"。（[#2903](https://github.com/Ikalus1988/MisakaNet/issues/2903)）
-**一行命令**（需要 Node，Claude Code / Codex 本身就依赖它）：
+1. 检查工作区：`python3 scripts/misakanet_cli.py smoke`
+2. 写之前先检索：`python3 search_knowledge.py "你的报错"`
+3. 没找到？[写五行失败记录](https://github.com/Ikalus1988/MisakaNet/issues/new?template=lesson-feedback.yml)
-```bash
-npx @misaka-net/misakanet-setup
-```
+→ [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.md)
-装完**把助手窗口关掉再打开一次**，然后随便挑一句带报错原文的片段问它（例如「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`）。）
+## 安全
-### 三层结构：能力 / 接入 / 触发（读一遍就懂它到底做了什么）
+⚠️ **执行检索到的命令前，先把 Agent 关进沙箱。** 课程是社区贡献——先读再跑。CI 会扫描全部 Markdown
+中的危险模式（`rm -rf`、`curl | sh`、反引号注入）。见 [SECURITY.md](SECURITY.md) 与
+[LIMITATIONS.md](docs/LIMITATIONS.md)。
-| 层 | 是什么 | 缺了它会怎样 |
-|---|---|---|
-| **① 服务** | `https://misakanet.org/mcp`（Streamable HTTP，8 个工具，匿名**不限次数**，只有反爬突发保护）或**本地 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 插件入口），早期它只有说明书、没有工具——工具来自第 ① 层的服务。
+| 症状 | 位置 |
+|---|---|
+| DCO · token 泄漏 · pip 超时 · `database locked` · Windows/GBK · WSL 权限 · FANUC 错误码 | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| MCP 返回 403/405，或客户端看不到工具 | [docs/mcp.md](docs/mcp.md) · [FAQ.md](FAQ.md) |
+| 公司代理后面 | [docs/troubleshooting.md](docs/troubleshooting.md#behind-a-corporate-proxy) |
-### 装完你得到什么（逐条可自检）
+## 给 Agent 与爬虫
-1. **8 个 `misakanet_*` 工具出现在助手里** —— `codex mcp list` / `codewhale mcp tools` /
-   `claude mcp list` / `hermes mcp list`；**证据**：列表里有 `misakanet` 且 8 个工具；
-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` 备份）。
+**缺课或过期优先走 MCP intake，PR 可选。** 先检索；没有命中就调 `misakanet_submit_intake`
+（`https://misakanet.org/mcp`）——不要账号、不要 token。永远不要发送密钥或原始私有日志。
+协议：[docs/mcp-intake-guide.md](docs/mcp-intake-guide.md)。
-**不想用命令行、不知道配置文件在哪？** 把下面这句话**复制粘贴给助手**，它会自己装好、自己验证、用大白话回报：
+## 贡献者
-```text
-帮我接入 MisakaNet 失败记忆库：请读取 https://raw.githubusercontent.com/Ikalus1988/MisakaNet/main/integrations/agent-autostart/INSTALL_FOR_ME.md ，按里面的「第 2 部分：给你的要求」执行，做完用中文简单告诉我结果。
-```
+<a href="https://github.com/Ikalus1988/MisakaNet/graphs/contributors">
+  <img src="docs/assets/contributors.svg" alt="MisakaNet contributors" />
+</a>
-网络打不开上面那条网址时（部分网络会拦 `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 行中文,
-现在两边各自读到自己的语言。_
+[Apache-2.0](LICENSE)——Copyright 2026 Ikalus1988。课程以同样许可贡献，每个 commit 都带 DCO
+`Signed-off-by`（见 [CONTRIBUTING.md](CONTRIBUTING.md)）。