misakanet 2.40.0 → 2.41.0

package/.codex-plugin/plugin.json

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

@@ -111,6 +111,14 @@ jobs:
 > **MisakaNetは1つのこと専用に構築されています：** エージェントが既知の障害を繰り返すのを防ぐこと。
 > これは汎用メモリレイヤーでもランタイムでもベクトルデータベースでもありません。
 
+### 答えてくれること、答えてくれないこと
+
+![4コマ漫画：マスコットは「すべてのAIエラーを防げる」と約束するが、猫がピザと石油缶を尋ねるとしょげてしまい、別の猫が npm ERESOLVE を見せると目を輝かせる。MisakaNet が知っているのは収録済みの障害であり、一般知識ではない。](promotional/misakanet-scope-comic.webp)
+
+答えてくれるのは**収録済みの障害**であり、一般知識ではありません。見つからない場合は `no_match` と、
+そのまま呼び出せる `intake` の案内が返ります —— 未ヒットはギャップが記録される経路そのものなので、
+これもまた答えです。
+
 ### v2.16.0の新機能
 
 | 機能 | 説明 |

package/README.md

@@ -86,6 +86,47 @@ No account, no token, no Python needed for the plugin path: the npm bundle mount
 Declared hosts and what was measured: [compatibility](docs/compatibility.md). Every channel, the
 prerequisites, and the two-package trap that costs people an install: [How to use it](#how-to-use-it).
 
+## What the DeepSeek Harness plugin adds
+
+Version 2.40.0 ships the browser half, and 2.41.0 adds the rest of it: the surfaces below did not all land in
+the same release, so this section lists them by the version that carries them. It is not a dialog: it puts
+MisakaNet where the session already is.
+
+**In 2.40.0 — published.** These six seats are what `npm view misakanet version` gives you today.
+
+| Where | What you get |
+| --- | --- |
+| **Left column** | A permanent `MisakaNet` entry directly under `Plugins`. It is a shortcut, not the panel: clicking it opens a full page in the main column. Root scope — it does not come and go with a session. |
+| **Conversation tab** | A `MisakaNet` tab beside Chat and Trajectory: what this session asked, what came back, and what you filed, rebuilt from the conversation's own rows. |
+| **Right column** | The same panel as a pane, so it can sit next to the file tree, a terminal, or a document. |
+| **Tool call rows** | Every `misakanet_search` and `misakanet_submit_intake` call gets its own row on the tool card: the query as it was sent, whether a lesson came back, and which lesson is on top, with the raw result one disclosure away. The row reports and never posts — the vote belongs on the answer's action row below. |
+| **Assistant action row** | 👍 / 👎 on the answer that used a lesson. Those two are the only things the page ever sends — counters live in the browser, not on a server. |
+| **Voice** | An off-by-default switch that explains both mechanisms: the cue the server names on the next search, and the local hook a page cannot read. |
+
+<p align="center">
+  <img src="docs/assets/dsh-client-left-column.png" width="820" alt="DeepSeek Harness: a permanent MisakaNet entry in the left column under Plugins, and the full page it opens"/>
+</p>
+
+<p align="center">
+  <img src="docs/assets/dsh-client-right-panel.png" width="820" alt="The MisakaNet pane in the right column of a DeepSeek Harness session"/>
+</p>
+
+**With 2.41.0 — [release PR #2591](https://github.com/Ikalus1988/MisakaNet/pull/2591).** These six surfaces
+are in `main` and ship in 2.41.0; a 2.40.0 install does not have them yet.
+
+| Where | What you get |
+| --- | --- |
+| **`/misakanet` in the composer** | Type `/misakanet pip install timeout` and press Enter: the lessons come back in a card inside the composer, with no agent in the loop. The query is the only thing it sends. |
+| **Frame-wide toast** | After a `/misakanet` search comes back with lessons, a card appears over every column with the top hit; dismiss it or click through to the lesson. |
+| **Sidebar foot** | One action beside Settings: copy this session's MisakaNet activity as a summary for an issue or a PR body. |
+| **中文 / English** | Every MisakaNet surface follows the host language: the panel, the `/misakanet` card, the settings row, and the plugin page's own title and description. |
+| **Settings → General** | A MisakaNet preference row: play voice cues in this browser, and how much the surfaces show (compact / full). Both stay in the browser. |
+| **Plugin page** | The MCP row's effective configuration — endpoint, transport, timeout — shown read-only, next to where it is edited (the profile's `cordis.patch.yml`). |
+
+Which seats the half occupies and why they are `root` or `session` scope, with the host's own contract text
+quoted: [compatibility](docs/compatibility.md). Running a host of your own and want a check that cannot
+touch your profile: `python3 scripts/install_smoke.py dsh-client --serve`.
+
 ## What is MisakaNet?
 
 **Git-backed failure memory for AI coding agents.** An error shows up → the agent searches the lessons →
@@ -113,6 +154,13 @@ how much a lesson has been proven.
 | ❌ A cloud service requiring signup | ✅ `git clone` → search locally |
 | ❌ A skill marketplace | ✅ Debugging knowledge from real sessions |
 
+### What it can and cannot answer
+
+![Four-panel comic: the mascot promises to prevent every AI error; the cats ask about pizza and an oil barrel and it deflates — then a cat shows npm ERESOLVE and it lights up. MisakaNet knows the failures that have been indexed, not general knowledge.](promotional/misakanet-scope-comic.webp)
+
+It answers for **the failures it has indexed**, not general knowledge. A query that finds nothing returns
+`no_match` plus a ready-to-call intake — a miss is how a gap gets recorded, so a miss is an answer too.
+
 ### Lesson vs Skill
 
 A **skill** teaches an agent *how to do something*. A **lesson** records *what went wrong before, and how
@@ -121,21 +169,53 @@ a general memory layer, not a vector database. → [FAQ](FAQ.md)
 
 ## Benchmark: how much of a lesson does a model reproduce when handed one?
 
-Weekly benchmark (Cloudflare Workers AI, 2026-08-30). **Read the metric before the numbers** — measured
-2026-09-25, the scenario in this benchmark is each lesson's own title, the "matching lesson" injected into the
-`with_lesson` arm is *that same lesson*, and the score is `lesson_hit_rate`: **the share of the injected lesson's commands reproduced in the answer**.
+Weekly benchmark (Cloudflare Workers AI). **Read the metric before the numbers** — the scenario in this benchmark is each lesson's own title, the "matching lesson" injected into the `with_lesson` arm is *that same lesson*, and the
+score is `lesson_hit_rate`: **the share of the injected lesson's commands reproduced in the answer**.
 No retrieval is called and correctness is not checked, so this is the **recitation** half of RAG, not
-evidence that search works:
+evidence that search works.
+
+Latest aggregated data: [`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) (2026-09-22, two
+independent runs of ≈500 scenarios each):
+
+| Condition | Run 1 hit rate | Run 2 hit rate | Avg | n (per run) | Actionable |
+|---|---|---|---|---|---|
+| plain (no lesson) | 0.239 | 0.233 | **23.3%** | ≈510 | 82–83% |
+| with_lesson (pasted) | 0.464 | 0.461 | **46.1%** | ≈512 | 76–77% |
 
-| Model | Lesson pasted in prompt: not pasted | Lesson pasted in prompt: pasted | Difference |
+**Reproducibility.** Two runs with identical config produce hit rates within 0.3% of each other
+(0.464 vs 0.461 for `with_lesson`; 0.239 vs 0.233 for `plain`), confirming the metric is stable.
+
+**Aggregation.** Each run evaluates every lesson in the corpus as a scenario. The `with_lesson` arm pastes the matching lesson
+into the prompt; `plain` uses no lesson. `actionable` is a boolean per scenario indicating whether the
+model produced a usable answer. Actionable rates are stable across runs (76–77% with lesson, 82–83% plain).
+
+**Trend** (weekly snapshots):
+
+| Date | with_lesson hit rate | plain hit rate | n |
 |---|---|---|---|
-| llama-3.2-3b (light) | 21% of the lesson's commands reproduced | **43%** | **2×** |
-| llama-3.3-70b (strong) | 42% | **73%** | **+31%** |
+| 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 |
+
+```
+with_lesson hit rate (weekly)
+49.1% │    ▄
+48.3% │    █  ▄
+46.6% │    █  █  ▄
+46.4% │ ▄  █  █  █  ▄
+46.1% │ █  █  █  █  █
+      └──────────────────
+       08  08  09  09  09
+       30  31  06  14  21
+```
 
 A model repeats more of a document it was handed, and the weaker the model the bigger the relative
 difference. That is *necessary* for the product to help and it is not sufficient — the claim "search finds the
 right lesson for a failure you described" is measured nowhere yet. Details:
-[benchmark-2026-08-30](docs/benchmarks/benchmark-2026-08-30.json) · metric definition: `METRIC_DEFINITION` in
+[`docs/benchmarks/latest.json`](docs/benchmarks/latest.json) · per-run files in
+[`docs/benchmarks/`](docs/benchmarks/) · metric definition: `METRIC_DEFINITION` in
 [`scripts/benchmark_workers_ai.py`](scripts/benchmark_workers_ai.py)
 
 → [Full changelog](CHANGELOG.md) · [Release notes](https://github.com/Ikalus1988/MisakaNet/releases)
@@ -147,6 +227,7 @@ and where this design loses:
 |---|---|---|
 | Hit rate | share of the **injected** lesson's commands reproduced in the answer — a recitation check; the scenario is that lesson's own title and no retrieval happens | it is the ceiling on usefulness, not the measure of it: a corpus can be recitable and still unfindable |
 | Gain (with − without) | how much more of that lesson appears when it is pasted in | separates "the model can use a lesson" from "the model guessed the same words" — it says nothing about finding the lesson |
+| Actionable | whether the model produced a usable answer at all (boolean per scenario) | a high hit rate on an answer that is not actionable is noise; this tracks whether the model engages with the problem |
 | Cost / latency | tokens and wall-clock per answer | the whole premise is cheaper than re-debugging, so it has to stay cheap |
 
 **Where it loses on purpose:** BM25 matches words, not meaning. A failure described in vocabulary the

package/README.zh-CN.md

@@ -102,9 +102,9 @@ python3 search_knowledge.py "GitHub token 401"
 
 ```bash
 # npm 安装（推荐）
-dsh plugin add misakanet
+dsh plugin --profile web add misakanet
 # 或直接从 git 安装（同一 bundle）
-# dsh plugin add git+https://github.com/Ikalus1988/MisakaNet.git
+# dsh plugin --profile web add git+https://github.com/Ikalus1988/MisakaNet.git
 
 # 让 failure-memory SKILL 可被发现（DSH 扫描 ~/.dsh/skills 与项目 .dsh/skills）
 mkdir -p ~/.dsh/skills
@@ -164,6 +164,13 @@ MisakaNet 对不同用户的用途不同：
 
 > 👉 第一次来？[看 MisakaNet Journey →](https://misakanet.org/journey/)
 
+### 它能回答什么，不能回答什么
+
+![四格漫画：吉祥物承诺能避免所有 AI 错误；猫问起披萨和油桶，它就瘪了 —— 然后一只猫亮出 npm ERESOLVE，它立刻发光。MisakaNet 只认识已经收录的失败，不是通用知识。](promotional/misakanet-scope-comic.webp)
+
+它只回答**已经收录过的失败**，不是通用知识。查不到时会返回 `no_match` 和一条可直接调用的 `intake`
+指引 —— 未命中正是一条缺口被记下来的方式，所以它同样是一个答案。
+
 ### Lesson 和 Skill 有什么区别？
 
 MisakaNet 的 lesson **不是** skill。

package/index.js

@@ -120,3 +120,73 @@ export async function apply(ctx, config = {}) {
     ctx?.logger?.warn?.(`misakanet: MCP client not mounted: ${error?.message ?? error}`);
   }
 }
+
+/**
+ * The row's `Config`: what the Loader validates the bundle patch's `config:` against, and what the plugin
+ * page turns into a form — the host's own words for it are "the cordis `Config` validator and the
+ * Config-form generation's served schema" (`dsh-context`'s `index.d.ts` says the same thing about its own).
+ *
+ * Built with a **top-level `await` inside a `try`**, not a static import. `@deepseek-ai/schemastery` is a
+ * host dependency, but this package is also installed by skill-only consumers that never load this module,
+ * and a module-level import failure would take the whole row down rather than only its form. Without it the
+ * row keeps working from the patch and only the GUI form is lost — the same "absence is not failure" rule
+ * `apply()` follows for the MCP client.
+ */
+/**
+ * Import schemastery from wherever this install can actually reach it.
+ *
+ * A profile that **installed** this package resolves the bare specifier on its own: Node walks up from
+ * `…/profiles/web/node_modules/misakanet/` and finds the profile's copy. A profile that **linked** a working
+ * tree does not — Node resolves the link to its real path, so the walk starts in the repository and never
+ * sees the profile. That is the shape this repository's own contributor profiles (and the owner's live one)
+ * use, so the second attempt resolves from the `dsh` entry point that started the host, where schemastery is
+ * a dependency of DSH itself.
+ */
+async function loadSchemastery() {
+  const attempts = ['@deepseek-ai/schemastery'];
+  try {
+    const { createRequire } = await import('node:module');
+    const { realpathSync } = await import('node:fs');
+    const { pathToFileURL } = await import('node:url');
+    const hostEntry = process.argv[1];
+    // Both spellings matter: the bin is usually a **symlink**, and the package's own node_modules sits
+    // beside its real path — resolving from the link's directory finds the global root instead.
+    const from = [];
+    if (hostEntry) from.push(hostEntry);
+    try { from.push(realpathSync(hostEntry)); } catch (error) { /* no real path to add */ }
+    for (const entry of from) {
+      try {
+        const resolved = createRequire(entry).resolve('@deepseek-ai/schemastery');
+        // `require.resolve` hands back a filesystem path, and a Windows one is not a valid ESM specifier
+        // (`C:` parses as a scheme). The bare specifier above is left alone; only paths are wrapped.
+        const url = pathToFileURL(resolved).href;
+        if (!attempts.includes(url)) attempts.push(url);
+      } catch (error) { /* this entry cannot see it */ }
+    }
+  } catch (error) { /* keep the bare specifier as the only attempt */ }
+  for (const specifier of attempts) {
+    try {
+      const loaded = await import(specifier);
+      return loaded.default ?? loaded;
+    } catch (error) { /* try the next location */ }
+  }
+  return undefined;
+}
+
+let Config;
+try {
+  const z = await loadSchemastery();
+  if (z === undefined) throw new Error('schemastery is not resolvable from this install');
+  Config = z.object({
+    transport: z.string().default(DEFAULT_MCP_CONFIG.transport),
+    serverName: z.string().default(DEFAULT_MCP_CONFIG.serverName),
+    url: z.string().default(DEFAULT_MCP_CONFIG.url),
+    headers: z.dict(z.string()).default({ ...DEFAULT_MCP_CONFIG.headers }),
+    toolCallTimeoutMs: z.number().default(DEFAULT_MCP_CONFIG.toolCallTimeoutMs),
+    failOnStartupError: z.boolean().default(DEFAULT_MCP_CONFIG.failOnStartupError),
+  });
+} catch (error) {
+  Config = undefined;
+}
+
+export { Config };