misakanet 2.50.0 → 3.0.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "misakanet",
-  "version": "2.50.0",
+  "version": "3.0.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

@@ -39,7 +39,7 @@ mcp-name: io.github.Ikalus1988/misakanet
 <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://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-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>
@@ -50,6 +50,7 @@ mcp-name: io.github.Ikalus1988/misakanet
   &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>
+  <a href="https://dshfind.com/en/plugins/Ikalus1988/MisakaNet?ref=badge"><img src="https://dshfind.com/api/badge/Ikalus1988/MisakaNet?metric=downloads&amp;lang=en" alt="dshfind の DSH プラグイン ダウンロード数"></a>
 </p>
 
 ---
@@ -107,9 +108,9 @@ intake を返します——「この失敗はまだ知らない」というコ
 |---|---|
 | ❌ 汎用メモリ | ✅ 失敗回復の知識レイヤー |
 | ❌ エージェントランタイム | ✅ 検索できるレッスンデータベース |
-| ❌ ベクトル DB / RAG スタック | ✅ BM25 キーワード検索、標準ライブラリのみ（Python ≥ 3.10 は必要） |
+| ❌ ベクトル DB / RAG スタック | ✅ BM25 キーワード検索、標準ライブラリのみ（Python ≥ 3.11 は必要） |
 | ❌ スキルマーケット | ✅ 実際のセッションから出たデバッグ知識 |
-| ❌ 検索ベンチマーク | ✅ 証拠で格付けされたコーパス。持っているベンチマークは停止済み |
+| ❌ 汎用ベンチマーク基盤 | ✅ 証拠で格付けされたコーパス。267 クエリの検索評価を公開、旧復唱ベンチマークは停止中 |
 
 ### 何に答え、何に答えないか
 
@@ -135,7 +136,26 @@ MisakaNet は索引済みの失敗にだけ答えます。一致が無いとき
   intake を返します。
 - **報告の速度がトリアージの速度を上回っています**：intake キューが正直なボトルネックです。
 
-## ベンチマーク：何を測り、なぜ停止したか
+## 検索ベンチマーク：267 クエリ、BM25 vs semantic fallback
+
+2026-10-27、hosted endpoint の検索経路を **267 クエリ**（レッスン 1 件につき 1 クエリ、Workers AI
+70B が生成）で評価しました。両 arm は同じ eval worker / corpus を使い、`MISAKANET_SEMANTIC` だけを
+切り替えています。
+
+| arm | R@1 | R@5 | no_match |
+|---|---|---|---|
+| BM25 | 0.210 | 0.225 | 0.712 |
+| semantic fallback | **0.446** | **0.472** | **0.453** |
+
+semantic fallback は R@1 を **23.6 ポイント**上げ、`no_match` を **25.9 ポイント**下げました。ただし
+R@1 は **0.446 < 0.46** で R@1 条件は未達、`no_match` は **0.453 ≤ 0.50** で no_match 条件は達成です。
+113 クエリの subset は 0.460/0.460、250 クエリは 0.404/0.504——fallback が効くことは示せますが、
+R@1 が解決したと宣言できるサンプルではありません。
+
+これは 300 レッスン中の 267 クエリで、650 全量ではありません。33 レッスンはクエリを生成できず、
+semantic 側は 2 件エラー、eval corpus も未更新です。→ [全文レポート](docs/benchmarks/retrieval-l1-267-2026-10-27.md)
+
+## 復唱ベンチマーク：何を測り、なぜ停止したか
 
 測ったのは 1 つの狭い問いだけです：**レッスンをモデルに渡したとき、そのレッスンのどれだけが返ってくるか。**
 指標は `lesson_hit_rate`——注入したレッスンのコマンドが回答に再現された割合です。数字の前に設定を読んで
@@ -222,7 +242,7 @@ with_lesson hit rate (per run date)
 （[理由](AGENTS.md#33-注册与配额)）。
 
 インストールの確認：`npx @misaka-net/misakanet-setup --verify`、取り消し：`--uninstall`。
-前提：インストーラーは Node ≥ 18、ライブラリと stdio サーバーは Python ≥ 3.10。
+前提：インストーラーは Node ≥ 18、ライブラリと stdio サーバーは Python ≥ 3.11。Python 3.10 は 2026-10-01 でサポート終了（EOL）になったため、このリリースには 3.11 以降が必要です——パッケージを更新する前にインタプリタを更新してください。
 
 ### GitHub Action として使う
 

package/README.md

@@ -39,7 +39,7 @@ A2A discovery via `.well-known/agent-card.json`.
 <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://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-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>
@@ -50,6 +50,7 @@ A2A discovery via `.well-known/agent-card.json`.
   &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>
+  <a href="https://dshfind.com/en/plugins/Ikalus1988/MisakaNet?ref=badge"><img src="https://dshfind.com/api/badge/Ikalus1988/MisakaNet?metric=downloads&amp;lang=en" alt="DSH plugin downloads on dshfind"></a>
 </p>
 
 ---
@@ -63,11 +64,13 @@ account or a token.
 |---|---|
 | **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 · MiniMax Code |
+| Installer-managed | Claude Code · Codex · Hermes · OpenClaw · codewhale · Cursor · Gemini CLI · Copilot CLI · OpenCode · Kiro · MiniMax Code · DeepSeek Harness |
 | **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.
+For DeepSeek Harness that is the **rules half only** (`$DSH_HOME/AGENTS.md`): its tools come from the
+plugin in the row above, which the installer prints as the one manual step.
 
 Updates: `dsh plugin --profile web update misakanet@latest`.
 Installer updates: `npx @misaka-net/misakanet-setup@latest`.
@@ -99,7 +102,9 @@ applies a fix somebody already verified → if nothing matches, the miss becomes
 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.
+Python standard library. The hosted MCP endpoint adds an **optional semantic fallback** (bge-m3 +
+Vectorize) only when BM25 returns no match; `MISAKANET_SEMANTIC=0` disables it. No vector database is
+required locally, and no server unless you want one.
 
 | | |
 |---|---|
@@ -111,9 +116,9 @@ Python standard library. No vector database, no embedding model, no server unles
 |---|---|
 | ❌ 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 mandatory vector database / RAG stack | ✅ BM25 first; optional, disable-able semantic fallback on the hosted endpoint |
 | ❌ a skill marketplace | ✅ debugging knowledge from real sessions |
-| ❌ a retrieval benchmark | ✅ a corpus graded by evidence; the benchmark we have is paused |
+| ❌ a general-purpose benchmark platform | ✅ a corpus graded by evidence; a 267-query retrieval run is published, and the older recitation benchmark is paused |
 
 ### What it answers — and what it does not
 
@@ -135,12 +140,55 @@ not to fail again. MisakaNet is only the second thing. → [FAQ](FAQ.md)
 - **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.
+- **Search is BM25 first; the hosted endpoint can fall back to embeddings.** Local/offline remains
+  stdlib BM25; the fallback runs only when BM25 returns no match, and `MISAKANET_SEMANTIC=0` turns it
+  off. A corpus gap is still a miss: the reply is `no_match` plus an intake, not an empty page.
 - **Reported gaps arrive faster than they are triaged.** The intake queue is the honest bottleneck.
+- **The corpus is downloadable and citable.** `data.misakanet.org` publishes a versioned
+  bundle — the full corpus, the benchmark query set, and every run artifact — with a
+  per-file SHA-256 and an explicit license per file ([DATASET.md](DATASET.md)). The counts
+  live in each version's `manifest.json`, not in prose.
 
-## Benchmark: what it measured, and why it is paused
+## Retrieval benchmark: 267 queries, BM25 vs semantic fallback
+
+On 2026-10-27 the hosted endpoint's retrieval path was evaluated on **267 queries, one per lesson**
+generated by Workers AI 70B. Both arms used the same eval worker and corpus; only
+`MISAKANET_SEMANTIC` changed.
+
+| arm | R@1 | R@5 | no_match |
+|---|---|---|---|
+| BM25 | 0.210 | 0.225 | 0.712 |
+| semantic fallback | **0.446** | **0.472** | **0.453** |
+
+The fallback improves R@1 by **23.6 points** and cuts `no_match` by **25.9 points**. It does **not**
+meet the R@1 half of the target (`0.446 < 0.46`); `no_match` is within the target
+(`0.453 ≤ 0.50`). A 113-query subset reaches 0.460/0.460, while 250 reaches 0.404/0.504: the sample is
+large enough to show the fallback works, not large enough to call R@1 solved.
+
+This is 267 queries from the 300-entry pool, not the full 650; 33 pool entries yielded no query, 2 semantic requests
+errored, and the eval corpus was not refreshed. → [full report](docs/benchmarks/retrieval-l1-267-2026-10-27.md)
+
+### What changed since: the gate, not the model
+
+The table above measures a configuration production no longer uses. Until 2026-10-28 the semantic path
+ran **only when BM25 returned nothing**, so a confident-but-wrong lexical hit suppressed it — 13 of the
+20 recorded misses were exactly that. For queries containing CJK characters the two ranked lists are now
+**fused** (reciprocal-rank) instead of one gating the other.
+
+Measured on the live endpoint, 64 Chinese queries, 0 transport failures:
+
+| bucket | n | before | after |
+|---|---|---|---|
+| zh → zh | 31 | 0.710 | **0.774** |
+| **zh → en** | 33 | 0.455 | **0.697** |
+| zh → en, low overlap | 14 | 0.214 | **0.500** |
+
+For scale: `bge-m3` pure cosine already reached 0.636 on the cross-lingual bucket, and a `gemini`
+embedding 0.727 — so most of the gap was the decision to consult the vector path, not the model.
+English queries are untouched (the fuse is gated on CJK characters) and sit at 15/20 against a floor of
+16, which is where they were before this change. → [full report](docs/benchmarks/cjk-fusion-2026-10-28.md)
+
+## Recitation 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.
@@ -208,14 +256,15 @@ command for every client. The ten supported clients, and what each one gets, are
 [the install page](https://misakanet.org/install/). Verify an install with
 `npx @misaka-net/misakanet-setup --verify`; undo it with `--uninstall`.
 Reads are anonymous and unlimited; registration is for writing ([why](AGENTS.md#33-注册与配额)).
-Node ≥ 18 for the installer, Python ≥ 3.10 for the library and stdio server.
+Node ≥ 18 for the installer, Python ≥ 3.11 for the library and stdio server. Python 3.10 reached end-of-life on 2026-10-01, so this release needs 3.11 or newer — upgrade the interpreter before upgrading the package.
 
 ### Other channels
 
 - **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.
+  session panel. The rules half (the "search before you act" block) is written by the installer into
+  `$DSH_HOME/AGENTS.md`; dsh has no plugin extension point for it, so the two halves stay separate.
 - **Call the endpoint yourself** — the `curl` in [Your first five minutes](#your-first-five-minutes).
 - **The library in your own code** — `pip install misakanet-core`.
 
@@ -227,7 +276,7 @@ Node ≥ 18 for the installer, Python ≥ 3.10 for the library and stdio server.
 - This repository (git) is also a **Claude Code plugin marketplace** —
   `/plugin marketplace add Ikalus1988/MisakaNet`.
 - `misakanet` (PyPI) is the stdio **MCP server** — `python3 -m misakanet.server`.
-- `misakanet-core` (PyPI) is the **library** (stdlib-only BM25) —
+- `misakanet-core` (PyPI) is the **library** (stdlib-only BM25; the hosted endpoint's semantic fallback is server-side) —
   `from misakanet.search import search_lessons`.
 
 ### Use it as a GitHub Action
@@ -271,6 +320,7 @@ jobs:
 | Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
 | Known limitations | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) |
 | Benchmarks | [docs/benchmarks/](docs/benchmarks/) |
+| Dataset (corpus + query sets, downloadable) | [DATASET.md](DATASET.md) · <https://data.misakanet.org/latest.json> |
 | 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) |
 
@@ -290,6 +340,8 @@ plan work around it. The only thing this repository has ever honoured is a merge
 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
 
+**This month's good first issue (Oct 26 – Nov 26):** [Bring one real failure](https://github.com/Ikalus1988/MisakaNet/issues/3901) — no code; the MCP intake needs no account; we help with the format.
+
 → [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

package/README.zh-CN.md

@@ -37,7 +37,7 @@ A2A（`.well-known/agent-card.json`）。
 <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://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-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>
@@ -48,6 +48,7 @@ A2A（`.well-known/agent-card.json`）。
   &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>
+  <a href="https://dshfind.com/en/plugins/Ikalus1988/MisakaNet?ref=badge"><img src="https://dshfind.com/api/badge/Ikalus1988/MisakaNet?metric=downloads&amp;lang=zh" alt="DSH 插件下载量（dshfind）"></a>
 </p>
 
 ---
@@ -104,9 +105,9 @@ curl -sS https://misakanet.org/mcp \
 |---|---|
 | ❌ 通用记忆系统 | ✅ 失败修复知识层 |
 | ❌ Agent 运行时 | ✅ 可检索的 lesson 数据库 |
-| ❌ 向量数据库 / RAG 栈 | ✅ BM25 关键词检索，纯标准库（仍需 Python ≥ 3.10） |
+| ❌ 向量数据库 / RAG 栈 | ✅ BM25 关键词检索，纯标准库（仍需 Python ≥ 3.11） |
 | ❌ 技能市场 | ✅ 来自真实会话的排错知识 |
-| ❌ 检索基准 | ✅ 按证据分级语料；我们有的那个基准已暂停 |
+| ❌ 通用基准平台 | ✅ 按证据分级语料；公开了 267 条检索评测，旧的复述基准已暂停 |
 
 ### 它能回答什么、不能回答什么
 
@@ -130,7 +131,24 @@ MisakaNet 只回答它已经索引过的失败。没有命中时，返回的是
   所以未命中返回 `no_match` 加 intake，而不是空白页。
 - **报料速度高于分诊速度**：intake 队列是诚实的瓶颈。
 
-## 基准：它测了什么，为什么暂停了
+## 检索评测：267 条，BM25 vs semantic fallback
+
+2026-10-27 在 hosted endpoint 上评测了 **267 条** query，每篇 lesson 一条，由 Workers AI 70B 生成。
+两个 arm 用同一个 eval worker 和 corpus，只切换 `MISAKANET_SEMANTIC`。
+
+| arm | R@1 | R@5 | no_match |
+|---|---|---|---|
+| BM25 | 0.210 | 0.225 | 0.712 |
+| semantic fallback | **0.446** | **0.472** | **0.453** |
+
+semantic fallback 把 R@1 提高 **23.6 个百分点**，把 `no_match` 降低 **25.9 个百分点**。但 R@1
+**0.446 < 0.46**，没有过 R@1 条件；`no_match` **0.453 ≤ 0.50**，过了 no_match 条件。113 条子集是
+0.460/0.460，250 条是 0.404/0.504——样本足以说明 fallback 有效，不足以宣布 R@1 已解决。
+
+这是 300 篇里的 267 条，不是完整 650；33 篇没有生成出 query，2 个 semantic 请求报错，eval corpus
+也没有刷新。→ [完整报告](docs/benchmarks/retrieval-l1-267-2026-10-27.md)
+
+## 复述基准：它测了什么，为什么暂停了
 
 只测了一个很窄的问题：**把一条 lesson 塞给模型，它会复述回多少？** 指标是 `lesson_hit_rate`——被注入
 lesson 里的命令有多大概率出现在回答里。读数字前先读设定：本基准的场景就是**每篇 lesson 自己的标题**，
@@ -212,7 +230,7 @@ with_lesson hit rate (per run date)
 `misakanet_write_lesson` 与 `misakanet_preflight`（[原因](AGENTS.md#33-注册与配额)）。
 
 验证安装：`npx @misaka-net/misakanet-setup --verify`；卸载：`--uninstall`。
-前置：安装器要 Node ≥ 18，库与 stdio server 要 Python ≥ 3.10。
+前置：安装器要 Node ≥ 18，库与 stdio server 要 Python ≥ 3.11。Python 3.10 已于 2026-10-01 结束支持（EOL），所以本版本需要 3.11 或更新——升级本包之前先升级解释器。
 
 ### 作为 GitHub Action 使用
 

package/lib/client.js

@@ -193,6 +193,12 @@ window.__ModuleLoader__.load({
 			"panel.asked.voteTwo": "2 human confirmations — recorded as a hint; the E4 rung comes from observable reuse, not a vote.",
 			"panel.asked.voteMore": "human confirmations — recorded as a hint; the E4 rung comes from observable reuse, not a vote.",
 			"panel.asked.noMatchTag": "no match",
+			// A degraded read is not a miss and not a zero: the server answered with `degraded: true`,
+			// `degraded_reasons` and a one-line `notice`, and the row has to say so instead of printing a
+			// count the corpus behind it could not stand behind (issue #3511).
+			"panel.asked.degradedTpl": "results may be incomplete ({reason})",
+			"panel.asked.degradedTag": "degraded",
+			"panel.asked.degradedWhy": "This read was degraded — it is not proof that no lesson exists.",
 			"panel.asked.agentNext": "Hand this line to the agent:",
 			"panel.asked.agentNextCopy": "Copy the next step",
 			"panel.asked.agentNextText": "Please record this gap with the MisakaNet intake so the next person finds it: misakanet_submit_intake problem: ",
@@ -277,6 +283,7 @@ window.__ModuleLoader__.load({
 			// and splitting the phrase across two slots later made it read `1 篇 篇被课程复用`.
 			"panel.strip.hitTpl": "{count} hit · ",
 			"panel.strip.missTpl": "{count} found nothing · ",
+			"panel.strip.degradedTpl": "{count} degraded · ",
 			"panel.strip.surfacedTpl": "{count} surfaced · ",
 			"panel.strip.helpfulTpl": "({n} helpful) · ",
 			"panel.strip.convertedTpl": "({n} became a lesson)",
@@ -359,6 +366,9 @@ window.__ModuleLoader__.load({
 			"panel.asked.voteTwo": "2 个人工确认 —— 只记为提示，不算证据：E4 那一档来自可观测的复用，投票给不了。",
 			"panel.asked.voteMore": "个人工确认 —— 只记为提示，不算证据：E4 那一档来自可观测的复用，投票给不了。",
 			"panel.asked.noMatchTag": "无命中",
+			"panel.asked.degradedTpl": "结果可能不完整（{reason}）",
+			"panel.asked.degradedTag": "降级读取",
+			"panel.asked.degradedWhy": "这是一次降级读取 —— 不代表真的没有这条课程。",
 			"panel.asked.agentNext": "把这行交给 agent：",
 			"panel.asked.agentNextCopy": "复制下一步",
 			"panel.asked.agentNextText": "请用 MisakaNet 报料记下这个缺口，让下一个人能搜到：misakanet_submit_intake problem: ",
@@ -427,6 +437,7 @@ window.__ModuleLoader__.load({
 			"settings.what.row": "条目",
 			"panel.strip.hitTpl": "{n} {unit}命中过课程 · ",
 			"panel.strip.missTpl": "{n} {unit}没命中 · ",
+			"panel.strip.degradedTpl": "{n} {unit}降级读取 · ",
 			"panel.strip.surfacedTpl": "{n} {unit}命中过课程 · ",
 			"panel.strip.helpfulTpl": "（{n} 有用） · ",
 			"panel.strip.convertedTpl": "（{n} 转化为课程）",
@@ -902,6 +913,11 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 				query: String(event.query || payload.query || ""),
 				hits: results.length,
 				noMatch: Boolean(payload.no_match),
+				// The server's own degradation report (issue #3512), kept with the sighting so every
+				// surface that renders this entry can say "incomplete" instead of "zero".
+				degraded: Boolean(payload.degraded),
+				degradedReasons: Array.isArray(payload.degraded_reasons) ? payload.degraded_reasons.slice() : [],
+				notice: typeof payload.notice === "string" ? payload.notice : "",
 				lessonId: top && top.id ? String(top.id) : "",
 				title: top ? String(top.title || top.id || "") : "",
 				evidence: top ? String(top.evidence_level || "") : "",
@@ -1078,6 +1094,20 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 			return n + " " + (n === 1 ? singular : plural);
 		}
 
+		/**
+		 * The reason a degraded read is degraded: the server's own stable reason ids, joined — the field
+		 * names are the branch points `searchDegraded` publishes, so the label names what failed rather
+		 * than paraphrasing it. A payload that claims `degraded` without reasons falls back to the tag
+		 * rather than printing an empty parenthesis.
+		 */
+		function degradedReason(payload) {
+			// Two shapes, one meaning: the wire payload (`degraded_reasons`) and the recorded session
+			// entry (`degradedReasons`) hold the same ids.
+			var reasons = payload && (Array.isArray(payload.degraded_reasons) ? payload.degraded_reasons
+				: (Array.isArray(payload.degradedReasons) ? payload.degradedReasons : []));
+			return reasons.length ? reasons.join(", ") : T("panel.asked.degradedTag");
+		}
+
 		/** mm:ss for today, else the date — the event's own time, never the render time. */
 		function clockOf(at) {
 			try {
@@ -1156,6 +1186,16 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 				head.push(h("span", { key: "state", style: DIM }, " " + T("panel.asked.searching")));
 			} else if (phase === "start") {
 				head.push(h("span", { key: "state" }, " " + (query || T("panel.asked.searching"))));
+			} else if (payload && payload.degraded) {
+				// A degraded read renders as the reason plus the server's one-line explanation — never as
+				// only a result count, and never as `no_match` ("no lesson matched"), which is the one
+				// sentence a frozen corpus cannot earn (issue #3511, measured 2026-10-18).
+				head.push(h("span", { key: "state" }, " " + T("panel.asked.degradedTpl",
+					{ reason: degradedReason(payload) })));
+				if (results.length) {
+					head.push(h("span", { key: "hits", style: DIM }, " · " + count(results.length, T("unit.lesson"), T("unit.lessons"))));
+				}
+				head.push(h("span", { key: "notice", style: DIM }, " · " + (payload.notice || T("panel.asked.degradedWhy"))));
 			} else if (payload && payload.no_match) {
 				head.push(h("span", { key: "state" }, " " + T("panel.asked.noMatch")));
 			} else if (results.length) {
@@ -1379,7 +1419,10 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 			var lessons = log ? Object.keys(log.lessons).map(function (id) { return log.lessons[id]; }) : [];
 			var stats = browserStats();
 			var withLesson = searches.filter(function (s) { return s.lessonId; }).length;
-			var noMatch = searches.filter(function (s) { return s.noMatch && !s.lessonId; }).length;
+			// A degraded search is counted in its own bucket and *not* as "found nothing": that phrase is
+			// the product's confident zero, and the server said the read could not earn it (issue #3511).
+			var degradedCount = searches.filter(function (s) { return s.degraded; }).length;
+			var noMatch = searches.filter(function (s) { return s.noMatch && !s.lessonId && !s.degraded; }).length;
 			var votes = log ? log.votes : [];
 			var helpful = votes.filter(function (v) { return v.kind === "helpful"; }).length;
 			var converted = intakes.filter(function (r) { return r.state === "converted"; }).length;
@@ -1517,6 +1560,9 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 				count(searches.length, T("unit.search"), T("unit.searches")) + " · " +
 				T("panel.strip.hitTpl", { count: count(withLesson, T("unit.lesson"), T("unit.lessons")), n: withLesson, unit: T("unit.lessons") }) +
 				T("panel.strip.missTpl", { count: count(noMatch, T("unit.lesson"), T("unit.lessons")), n: noMatch, unit: T("unit.lessons") }) +
+				// …and the degraded bucket says so out loud, so a degraded search is never counted as a
+				// normal one without a label of its own.
+				T("panel.strip.degradedTpl", { count: count(degradedCount, T("unit.search"), T("unit.searches")), n: degradedCount, unit: T("unit.searches") }) +
 				T("panel.strip.surfacedTpl", { count: count(lessons.length, T("unit.lesson"), T("unit.lessons")), n: lessons.length, unit: T("unit.lessons") }) +
 				count(votes.length, T("unit.vote"), T("unit.votes")) + " " + T("panel.strip.helpfulTpl", { count: count(helpful, T("unit.vote"), T("unit.votes")), n: helpful, unit: T("unit.votes") }) +
 				count(intakes.length, T("unit.report"), T("unit.reports")) + " " + T("panel.strip.convertedTpl", { count: count(converted, T("unit.report"), T("unit.reports")), n: converted, unit: T("unit.reports") })));
@@ -1614,7 +1660,11 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 						? (entry.voteKind === "helpful" ? T("panel.asked.voteHelpful") : T("panel.asked.voteNotHelpful"))
 						: (entry.lessonId ? T("panel.asked.voteNone") : T("panel.asked.voteNoLesson"));
 					var said = panelVotes[key];
-					var missed = Boolean(entry.noMatch) || !entry.lessonId;
+					// A degraded sighting is not a miss: "found nothing" is exactly the claim a frozen
+					// corpus cannot make, and offering the intake line from one would file a gap for a
+					// lesson that may well exist (issue #3511).
+					var isDegraded = Boolean(entry.degraded);
+					var missed = !isDegraded && (Boolean(entry.noMatch) || !entry.lessonId);
 					var controls = [];
 					if (entry.lessonId && !entry.voted) {
 						controls.push(h("button", {
@@ -1643,9 +1693,14 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 						h("div", { key: "head", style: { borderLeft: "2px solid " + (missed ? "rgba(127,127,127,0.9)" : "transparent"), paddingLeft: missed ? "6px" : "8px" } },
 							h("span", { style: DIM }, clockOf(entry.at) + "  "),
 							h("span", {}, entry.query || T("panel.asked.noQuery")),
-							h("span", { style: DIM }, "  " + (entry.noMatch ? T("panel.asked.nothingFound") : count(entry.hits, T("unit.lesson")))),
+							h("span", { style: DIM }, "  " + (isDegraded
+								? T("panel.asked.degradedTpl", { reason: degradedReason(entry) })
+									+ (entry.hits ? " · " + count(entry.hits, T("unit.lesson")) : "")
+								: (entry.noMatch ? T("panel.asked.nothingFound") : count(entry.hits, T("unit.lesson"))))),
 							missed ? h("span", { style: Object.assign({}, DIM, { border: "1px solid " + MUTED, borderRadius: "4px", padding: "0 4px", marginLeft: "4px", fontSize: "11px" }) },
 								T("panel.asked.noMatchTag")) : null,
+							isDegraded ? h("span", { style: Object.assign({}, DIM, { border: "1px solid " + MUTED, borderRadius: "4px", padding: "0 4px", marginLeft: "4px", fontSize: "11px" }) },
+								T("panel.asked.degradedTag")) : null,
 							entry.title ? h("span", { style: DIM }, "  · top: " + entry.title + (entry.evidence ? " (" + entry.evidence + ")" : "")) : null,
 							entry.lessonId ? h("span", { style: DIM }, "  · " + vote) : null),
 					];
@@ -1655,6 +1710,10 @@ var DEFAULT_MCP_URL = "https://misakanet.org/mcp";
 							h("code", { style: { fontSize: "11px" } }, intakeNextStep(entry.query))));
 						lines.push(h("div", { key: "why", style: DIM }, T("panel.asked.agentNextWhy")));
 					}
+					if (isDegraded) {
+						// The one-line explanation, from the server's own `notice` when it sent one.
+						lines.push(h("div", { key: "why", style: DIM }, entry.notice || T("panel.asked.degradedWhy")));
+					}
 					if (controls.length || said) {
 						lines.push(h("div", { key: "do" }, controls,
 							said ? h("span", { style: DIM }, said) : null));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "misakanet",
-  "version": "2.50.0",
+  "version": "3.0.0",
   "license": "Apache-2.0",
   "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.",
   "icon": "icon.svg",
@@ -80,7 +80,7 @@
     "preview": "wrangler dev"
   },
   "devDependencies": {
-    "wrangler": "^4.151.0"
+    "wrangler": "^4.152.0"
   },
   "overrides": {
     "sharp": "0.35.5",