@misaka-net/misakanet-setup 0.5.6 → 0.7.0

package/README.md

@@ -1,8 +1,15 @@
 # @misaka-net/misakanet-setup
 
-One command to teach your **Claude Code**, **Codex**, **Hermes**, **OpenClaw** or **codewhale** to
-check MisakaNet's failure lessons before repeating a mistake — and to distil the session's reusable
-lessons at a checkpoint.
+One command to teach your **Claude Code**, **Codex**, **Hermes**, **OpenClaw**, **codewhale**,
+**Cursor**, **Gemini CLI**, **Copilot CLI**, **OpenCode**, **Kiro** or **MiniMax Code** to
+check MisakaNet's failure lessons before repeating a mistake — and to write up the reusable lessons
+this session produced, at a checkpoint.
+
+**What it writes:** an MCP endpoint into each agent config, rules blocks for the clients that take
+one, and a local hook for Claude Code. **What leaves this machine:** at most one anonymous request
+while the installer runs; afterwards, only what the agent itself sends — with one opt-in exception:
+`MISAKANET_HOOK_FETCH=1` (off by default) makes the hook itself send the failed call's error text
+(or the command, when the tool gave no error text) as a search query.
 
 ```bash
 npx @misaka-net/misakanet-setup
@@ -16,20 +23,99 @@ knowledge base on its own instead of guessing.
 
 | # | Goal | Mechanism |
 |---|---|---|
-| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token when registration succeeds — reads need no token (anonymous reads are unmetered since 2026-09-18); the token is what opens the **write** path. Every entry also carries the self-declared context hints `X-MisakaNet-Client` / `-Agent` / `-Os` / `-Version`, which the endpoint records on the read's analytics row and never treats as identity (`codewhale` is the one exception: its server entry has no custom-header field). Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. All four are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
-| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules). Wording is **imperative first** ("必须先调 misakanet_search") rather than descriptive, because a field test showed a weaker model reads a descriptive block as background and never calls the tool |
+| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token when registration succeeds — reads need no token (anonymous reads are unmetered since 2026-09-18); the token is what opens the **write** path. Every entry also carries the self-declared context hints `X-MisakaNet-Client` / `-Agent` / `-Os` / `-Version`, which the endpoint records on the read's analytics row and never treats as identity (`codewhale` is the one exception: its server entry has no custom-header field). Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. Six clients take the same idea in one file each, and **each file uses its own key path and URL field** — they are not interchangeable, and a copied entry with the wrong key fails silently (no error, the server simply never appears):
+
+| client | file | container | URL field |
+|---|---|---|---|
+| Cursor | `~/.cursor/mcp.json` | `mcpServers` | `url` |
+| Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | **`httpUrl`** (its `url` means SSE) |
+| Copilot CLI | `~/.copilot/mcp-config.json` | `mcpServers` | `url`, with `type: "http"` |
+| OpenCode | `~/.config/opencode/opencode.json` | **`mcp`** | `url`, with `type: "remote"` |
+| Kiro | `~/.kiro/settings/mcp.json` | `mcpServers` | `url` |
+| MiniMax Code | `~/.minimax/plugins/misakanet/.claude-plugin/plugin.json` | `mcpServers` | `url`, with `type: "http"` (a **plugin manifest**, not a user config file) |
+
+There is one difference in kind in that last row: mcode ignores `~/.minimax/config.yaml`'s
+`mcpServers` entirely and reads **plugin directories** instead, so an entry written there would
+look installed and register nothing. Its manifest also comes with the rules block, in
+`~/.minimax/AGENTS.md`; the measured shape, the `mcode plugin list` check and the proxy caveat
+(`NODE_USE_ENV_PROXY=1`) are in `docs/integrations/mcode.md`.
+
+All of them are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
+| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` / `~/.minimax/AGENTS.md` (mcode's global scope). **The five JSON-config clients are the exception: they get none**, because their rules are project-scoped (`.cursor/rules/*.mdc`, `GEMINI.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `.kiro/steering/*.md`) and the installer cannot know where your projects live — the install output says so, with the project-side action for each client, instead of implying behaviour changed (issue, retry, risky-operation triggers; desensitisation rules). Wording is **imperative first** ("必须先调 misakanet_search") rather than descriptive, because a field test showed a weaker model reads a descriptive block as background and never calls the tool |
 | 4 | *(opt-in)* you **hear** it | `--voice` adds a `PostToolUse` hook that plays the cue the server asked for (`lesson-found` / `failure-warning` / `connect-success` / `pair-success`). Off by default; mute with `MISAKANET_VOICE=0`; see `docs/integrations/mcp-voice-hooks.md` |
-| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
+| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "write up the reusable lessons and submit them" reminder — the agent does that writing and that submitting, by hand, and the hook itself sends nothing by default; a failed tool call injects a "search before you retry" reminder built from the error text, and only with `MISAKANET_HOOK_FETCH=1` (off by default) does the hook itself send that error text as a search query. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
 
 Without (3) a rule saying "summarise every 20 turns" never fires — agents do not keep
 counters. Without (1)/(2) the hook has nothing to call.
 
+### dsh is not a file target — it is a plugin
+
+dsh takes its MCP servers from a **plugin bundle**, not from a JSON file. Its instruction files are a
+chain: **`$DSH_HOME/AGENTS.md`** (user-global, default `~/.dsh/AGENTS.md`, applies to every session)
+first, then the project's `AGENTS.md`/`CLAUDE.md` from the project root down to the working directory
+(`@deepseek-ai/dsh-agent-instructions`, byte-budgeted at 65,536 by default). It has no Claude-Code-style
+hooks.
+
+So dsh takes **two manual steps that do not know about each other**, and this installer does neither of
+them — it writes no file under `~/.dsh`:
+
+```bash
+dsh plugin --profile web add misakanet   # ① the tools (mcp__misakanet__*) — dsh's own command
+# ② you paste the rules block into ~/.dsh/AGENTS.md (global) or the project's AGENTS.md
+```
+
+Measured 2026-10-17: writing `~/.dsh/AGENTS.md` is picked up as `user-global` instructions on the next
+message, with no restart.
+
+Measured 2026-10-17: installing the current `misakanet` takes ~1s into `~/.dsh/profiles/web`; the plugin's
+`index.js` mounts the MCP client and `lib/client.js` is the web panel — **neither injects a rule**,
+which is why ② is a separate, manual step.
+
+**Upgrading the installer does not refresh that block.** Nothing rewrites text you pasted, and the
+installer only refreshes the files it manages (for Claude Code, `~/.claude/CLAUDE.md`). Measured
+2026-10-23 (issue #3773): one machine's `~/.dsh/AGENTS.md` still carried the old block — its last line
+read `脱敏：密钥/凭据→<REDACTED>…` — while the same installer had just written the current one
+(`脱敏：已由代码自动完成…`) to `~/.claude/CLAUDE.md`. Re-paste after an upgrade, and check by comparing
+that line; the copy in `docs/integrations/dsh.md` can lag too.
+
+**Uninstalling takes two steps, and the second one is yours.** `dsh plugin --profile web remove misakanet`
+removes the tools; the rules block stays in `~/.dsh/AGENTS.md` (or the project's `AGENTS.md`), and there is
+no `misakanet:start` / `misakanet:end` marker to lift it — the installer never put one there, because it
+never wrote that file. Remove the block by hand, then check:
+
+```bash
+grep -c misakanet "${DSH_HOME:-$HOME/.dsh}/AGENTS.md"   # expected 0; a missing file errors, which is also clean
+```
+
+Until the block is removed, a new dsh session still follows it and calls `mcp__misakanet__*` tools that
+no longer exist.
+
+**Why it is not mechanised yet.** dsh's MCP servers come from the plugin bundle and its instructions come
+from the `AGENTS.md` chain — two entry points this installer has no path into: it only writes the files on
+its own target list, and dsh's files are not on it. A mechanical fix (a marker pair around the block, plus
+an uninstall branch) **is not implemented; it is follow-up work**. Until then,
+`dsh plugin --profile web remove misakanet` does not take the block with it.
+
+Full guide: `docs/integrations/dsh.md`.
+
 ## Flags
 
 ```bash
 npx @misaka-net/misakanet-setup --dry-run     # show what would change, write nothing
-npx @misaka-net/misakanet-setup --verify      # READY / NOT READY, installed version, and the fix for each gap
+npx @misaka-net/misakanet-setup --verify      # READY / NOT READY / could not verify, installed version,
+                                             #  and the fix for each gap (exit codes: 0 / 1 / 2)
+                                             # two sections, two questions: 端点/可用性 (can you use it — the
+                                             #  endpoint answers) and 安装完整性 (are the files we prefer
+                                             #  written); one failing does not condemn the other, and a file
+                                             #  we cannot write says 装不了 with its cause — not 没装 with
+                                             #  the one fix that cannot work ("re-run the installer")
 npx @misaka-net/misakanet-setup --only claude # one agent only
+npx @misaka-net/misakanet-setup --list-writes # only prints what it would write (file | action | how to undo), writes nothing
+                                             # (the install preview shows the same list; this one is for an operator who
+                                             #  has to approve it before it happens)
+npx @misaka-net/misakanet-setup --mcp-only    # register the endpoint only, change no agent behaviour — no rules block,
+                                             # no hook; for permission tiers, where tier ① is the endpoint and tiers ②/③
+                                             # are what change how the agent behaves
 npx @misaka-net/misakanet-setup --no-register # read-only, no anonymous token
 npx @misaka-net/misakanet-setup --upgrade     # same as installing the latest (the command is idempotent)
                                              # re-running also *refreshes* an older hook (the previous copy
@@ -56,18 +142,22 @@ npx @misaka-net/misakanet-setup --uninstall   # remove exactly what it added
 
 `--report` alone **always exits 0** when it prints a report, and that is deliberate: the report is
 evidence meant to be pasted into an issue or a CI log, and a nonzero exit there turns "collect the
-evidence" into a failing step. The gate is the opt-in `--strict` form (alias: `--ci`), which prints
-the *same* YAML and then judges it:
+evidence" into a failing step. The gates are the opt-in `--strict` form (alias: `--ci`) and
+`--verify`, which print the same evidence and then use the same three codes:
 
-| code | `--report --strict` (and `--report-json --strict`) | meaning |
+| code | `--verify` / `--report --strict` | meaning |
 |---|---|---|
-| `0` | READY | the report says `verify: READY` **and** `open-items: 0` |
-| `1` | NOT READY | `verify: NOT READY` — including when `open-items > 0`; the report lists one line per open item, each with its fix |
-| `2` | could not run | the report could not be produced at all (the tool failed instead of judging). This is **not** a verdict about your machine: on `2` there is no report at all (neither YAML nor JSON), only a one-line reason on stderr |
+| `0` | READY | the endpoint handshake succeeded (`endpoint-tools` > 0) **and** `open-items: 0` |
+| `1` | NOT READY | a **machine** problem: no supported assistant was detected at all (so nothing was installed), our files are missing or unwritable, an MCP entry points at the wrong URL, or the endpoint really is `unreachable` / `non-mcp` |
+| `2` | could not verify | the tool could **not give a machine verdict**: the probe was a `timeout` or `inconclusive-proxy` (a proxy is configured that this Node does not use), or the report could not be produced at all (the CLI crashed). With `--report --strict` the YAML/JSON is still printed first — `endpoint-probe` says which doubt it was — and only the exit code changes. A crash prints no report at all, only a one-line reason on stderr |
+
+`1` versus `2` is the difference between "fix the machine" and "fix the network/the tool": a
+timeout or an unusable proxy says nothing about whether this machine is installed correctly, so it
+must not be reported as `1` (that sends people to debug a working install) and must not be `0`
+either (a script reads `0` as READY). `--report` alone stays `0` in all three cases.
 
 The convention is the repository-wide one (`0 = fine, 1 = found problems, 2 = could not run`, same as
-`scripts/check_workflow_scripts.py`), so a CI step can tell "the environment is unhealthy" (fix the
-machine) from "the checker broke" (fix the checker).
+`scripts/check_workflow_scripts.py`).
 
 The last two fields of the report, `tools-visible` and `live-call-evidence`, are **blank fields a
 human fills in afterwards** — they are never read back by the tool and **never influence the exit
@@ -98,6 +188,10 @@ GPO / Intune / Jamf / Ansible snippets, and the section an IT security review ac
 `--no-register` avoids registration entirely):
 [`docs/maintainer/enterprise-deployment.md`](https://github.com/Ikalus1988/MisakaNet/blob/main/docs/maintainer/enterprise-deployment.md).
 
+A reviewer-facing landing page — the same boundary questions, plus an explicit list of what does
+**not** exist yet (no compliance certifications, no organisation-level audit export, no self-hosted
+form of the hosted endpoint): <https://misakanet.org/enterprise/>.
+
 The short version for a deployment script — two commands, both silent:
 
 ```bash
@@ -153,9 +247,32 @@ npx @misaka-net/misakanet-setup@latest
 ## Offline / restricted networks
 
 The hook ships inside the npm tarball, so installing needs no download beyond npm itself.
-Registration is best-effort: without it you keep the anonymous read path (5 reads/day/IP)
+Registration is best-effort: without it you keep the anonymous read path (unmetered since 2026-09-18; only a per-address burst window applies)
 and the installer says so in plain words.
 
+**Behind a corporate proxy, read the probe line before believing it.** `--verify` probes the
+endpoint with Node's `fetch`, and Node ignores `HTTP_PROXY` / `HTTPS_PROXY` unless the runtime is
+told to use them — `NODE_USE_ENV_PROXY=1` or `--use-env-proxy`, with `fetch` support in Node
+≥ 22.21.0 / 24.0.0 ([Node docs](https://nodejs.org/learn/http/enterprise-network-configuration)).
+On a proxy machine the probe can therefore fail while your agent reaches the endpoint fine. The
+report now says which of the two it is:
+
+```bash
+NODE_USE_ENV_PROXY=1 npx @misaka-net/misakanet-setup --verify   # let Node use the proxy
+curl -sS https://misakanet.org/mcp -H 'Accept: application/json' \
+  -H 'MCP-Protocol-Version: 2025-06-18' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+`endpoint-probe: inconclusive-proxy` in `--report` means exactly this: a proxy is configured, this
+process could not use it, so the `endpoint-reachable` boolean above it says nothing. `--verify` and
+`--strict` / `--ci` then exit **2** ("could not verify") — not `0` (a script reads that as READY)
+and not `1` (that would send you to fix a machine that may be perfectly fine; `--verify` itself
+still tells you whether the installed files are complete). If your proxy also intercepts TLS, add
+`NODE_USE_SYSTEM_CA=1`.
+
+The Python installer (`integrations/agent-autostart/install_misakanet_agent.py`) needs none of this:
+it uses `urllib`, which honours the proxy environment variables by default.
+
 ## Requires
 
 Node 18+ (the same runtime your assistant already uses). No dependencies, no Python.