@misaka-net/misakanet-setup 0.8.0 → 0.9.0

package/README.md

@@ -1,9 +1,14 @@
 # @misaka-net/misakanet-setup
 
 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.
+**Cursor**, **Gemini CLI**, **Copilot CLI**, **OpenCode**, **Kiro**, **MiniMax Code** or
+**DeepSeek Harness** to check MisakaNet's failure lessons before repeating a mistake — and to write
+up the reusable lessons this session produced, at a checkpoint.
+
+For **DeepSeek Harness (dsh)** that command writes the **rules half only** (`$DSH_HOME/AGENTS.md`)
+and prints the one command its tools need (`dsh plugin --profile web add misakanet`); everything
+else in this README applies to all twelve exactly as written. The split, and why dsh is the one
+target shaped that way, is in [dsh: the rules half, written](#dsh-the-rules-half-written--the-plugin-half-printed).
 
 **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
@@ -47,60 +52,66 @@ look installed and register nothing. Its manifest also comes with the rules bloc
 (`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 |
+| 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) / `$DSH_HOME/AGENTS.md` (dsh, default `~/.dsh`). **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 "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: the rules half, written — the plugin half, printed
 
 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.
+hooks — and no plugin extension point that could inject a rule, which is why the rules are a **file**
+and the tools are a **plugin**, and why the two cannot be one write.
 
-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`:
+So dsh is **one file target and one printed step**. The installer writes the half a file can hold and
+names the other half instead of doing neither:
 
 ```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
+npx @misaka-net/misakanet-setup --only dsh       # ① the rules block → $DSH_HOME/AGENTS.md
+dsh plugin --profile web add misakanet           # ② the tools (mcp__misakanet__*) — dsh's own command
 ```
 
+Order does not matter; skipping ② leaves rules without tools, and the run says so with the exact
+command (`! dsh：工具在插件包里，安装器不写这个文件 → 跑 \`dsh plugin --profile web add misakanet\``).
+`--list-writes --only dsh` names the file and its tier (`tier2 ② 写规则块 … ~/.dsh/AGENTS.md`), and
+`--mcp-only` skips it, like every other rules block.
+
 Measured 2026-10-17: writing `~/.dsh/AGENTS.md` is picked up as `user-global` instructions on the next
-message, with no restart.
+message, with no restart. Measured 2026-10-17: installing the plugin takes ~1s into
+`~/.dsh/profiles/web`, and neither `index.js` (the MCP client mount) nor `lib/client.js` (the web
+panel) injects a rule.
 
-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.
+Measured 2026-10-30, on a machine whose block had been pasted by hand: the unmarked text was adopted
+into a marked block (`<!-- misakanet:start -->` … `<!-- misakanet:end -->`, header preserved,
+1,474 bytes) and the next message reloaded it — so an older hand-pasted copy is upgraded in place
+rather than duplicated.
 
-**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.
+**A sandbox home stays a sandbox.** `DSH_HOME` is a user setting, so it is honoured **only when the
+installer is addressing the real home**; with `--home <dir>` every write stays under `<dir>`. That is
+not a footnote: before 2026-10-30 the package's own test run wrote the *real* `~/.dsh/AGENTS.md`
+(truncated it to 35 bytes) because the suite inherits `DSH_HOME` from the shell.
 
-**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:
+**Uninstalling is two steps, and neither takes the other's half:**
 
 ```bash
-grep -c misakanet "${DSH_HOME:-$HOME/.dsh}/AGENTS.md"   # expected 0; a missing file errors, which is also clean
+npx @misaka-net/misakanet-setup --uninstall      # ① strips the marked block
+dsh plugin --profile web remove misakanet        # ② removes the tools
 ```
 
-Until the block is removed, a new dsh session still follows it and calls `mcp__misakanet__*` tools that
-no longer exist.
+Doing ① alone leaves a plugin nobody's rules mention; doing ② alone leaves a session following rules
+that call tools which no longer exist. `--uninstall` keeps `AGENTS.md.misakanet.bak` next to the file
+it emptied, and deletes the file outright when it held nothing but the block.
 
-**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.
+**Upgrades now refresh the block**, which is the one thing the old hand-pasted flow could not do
+(measured 2026-10-23, issue #3773: a machine's block was still the old `脱敏：密钥/凭据→<REDACTED>…`
+wording while the same installer had just written the current one to `~/.claude/CLAUDE.md`). Re-running
+the installer updates it in place; the copy in `docs/integrations/dsh.md` can still lag, and the
+installer's output is the criterion.
 
 Full guide: `docs/integrations/dsh.md`.
 

package/bin/misakanet-setup.mjs

@@ -132,7 +132,7 @@ const SILENT = has('--silent');
 const REPORT_JSON = has('--report-json');
 const HOME = resolve(valueOf('--home', homedir()));
 const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale',
-                'cursor', 'gemini', 'copilot', 'opencode', 'kiro', 'mcode'];
+                'cursor', 'gemini', 'copilot', 'opencode', 'kiro', 'mcode', 'dsh'];
 
 /**
  * The three line lists, and what every line knows about itself.
@@ -197,7 +197,7 @@ function readText(path) {
  * except the two that name the version (measured 2026-10-22: the 0.6.0 release pull request
  * failed 9 e2e legs on exactly that).
  */
-const VERSION = '0.8.0'  // x-release-please-version
+const VERSION = '0.9.0'  // x-release-please-version
 
 /**
  * The shape of a client id, in one place.
@@ -483,6 +483,8 @@ const AGENT_LABELS = {
   hermes: 'Hermes',
   openclaw: 'OpenClaw',
   codewhale: 'Codewhale',
+  // dsh is a plugin-bundle client: the installer writes only its rules half (see installDsh).
+  dsh: 'dsh',
   ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS).map(([id, spec]) => [id, spec.label])),
   // Not an MCP-only target: it takes a rules block too (see `installMcode`), so its label cannot be
   // read from that table.
@@ -566,6 +568,9 @@ const AGENT_WRITE_PATHS = {
   // carries the rules block (②). Listing both here is what makes the preview, `--list-writes` and
   // the permission pre-check agree with `installMcode`.
   mcode: (home) => [join(home, MCODE_PLUGIN_REL), join(home, MCODE_RULES_REL)],
+  // dsh reads its instructions from $DSH_HOME/AGENTS.md (default ~/.dsh). Its MCP servers
+  // come from a plugin bundle this installer cannot write, so one file is the whole manifest.
+  dsh: (home) => [join(dshHome(home), 'AGENTS.md')],
   openclaw: () => openclawWorkspaces().map((workspace) => join(workspace, 'AGENTS.md')),
 };
 
@@ -1245,6 +1250,40 @@ let lastResponseOk = false;
 // `--verify` can print is what actually came back (`{}` is not a diagnosis).
 let lastResponsePreview = '';
 
+// The server's retry horizon on the last response, in seconds, when it sent one: the `Retry-After`
+// response header (seconds or an HTTP-date), the standard shape `docs/index.html` already reads on
+// 429s. Per-request, so a horizon from an earlier call can never leak into a later failure's words.
+let lastRetryAfterSeconds = null;
+
+/** `Retry-After` → seconds. Both forms the header allows; anything else is "no horizon", not 0. */
+function retryAfterSeconds(headerValue) {
+  const raw = String(headerValue || '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) return Number(raw);
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.round((at - Date.now()) / 1000));
+}
+
+/**
+ * How long the server says to wait before re-running, when it says. The failure body's `retry_after`
+ * (seconds, HTTP `Retry-After` semantics) wins over the header, and neither is guessed: a server that
+ * stays silent gets no horizon sentence at all.
+ */
+function retryHorizonOf(result) {
+  const fromBody = result && (result.retry_after ?? result.retry_after_seconds);
+  const n = Number(fromBody);
+  if (Number.isFinite(n) && n > 0) return Math.round(n);
+  return lastRetryAfterSeconds;
+}
+
+/** "45 秒" / "15 分钟" / "2 小时" — the horizon in the words a person reads a clock in. */
+function humanWait(seconds) {
+  if (seconds < 60) return `${seconds} 秒`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)} 分钟`;
+  return `${Math.round(seconds / 3600)} 小时`;
+}
+
 async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   const headers = {
     'Content-Type': 'application/json',
@@ -1260,6 +1299,7 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   lastRequestKind = '';
   lastResponseOk = false;
   lastResponsePreview = '';
+  lastRetryAfterSeconds = null;
   try {
     const response = await fetch(urlOverride || ENDPOINT, {
       method: 'POST',
@@ -1271,6 +1311,9 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
     // below, not by this line — but "it answered with something that is not a handshake" and
     // "nothing answered" are different facts (see probeOutcome()).
     lastResponseOk = true;
+    lastRetryAfterSeconds = retryAfterSeconds(
+      response.headers && typeof response.headers.get === 'function'
+        ? response.headers.get('Retry-After') : null);
     const payload = await response.json();
     lastResponsePreview = JSON.stringify(payload).slice(0, 160);
     if (payload && payload.error) {
@@ -1618,8 +1661,15 @@ async function ensureIdentity() {
       : serverCode
         ? `服务端拒绝了这次注册（${serverCode}）`
         : `多半是网络（${lastRequestError || '没有收到响应'}）`;
+    // …and when the server says *how long* to wait, say that too instead of "稍后". The horizon is
+    // never guessed and never rounded into a promise: a server that sent none keeps the vague
+    // wording, because a made-up wait is the same lie as the network guess this replaced (issue
+    // #3511 — the retry-horizon half; the `code` half landed with #3512).
+    const horizon = retryHorizonOf(result);
     need(`匿名注册没成功：${cause} → 读课程不受影响，但写入类工具（write_lesson）现在用不了；`
-      + '稍后重跑本命令就能拿到 token'
+      + (horizon
+        ? `约 ${humanWait(horizon)}后重跑本命令就能拿到 token（服务端给出的重试窗口）`
+        : '稍后重跑本命令就能拿到 token')
       + (serverHint ? `（服务端提示：${serverHint}）` : ''));
     return '';
   }
@@ -1659,6 +1709,9 @@ function mcpEntryPresent(agent) {
 }
 
 function detect(agent) {
+  // dsh may live outside $HOME (DSH_HOME), so it is answered by its own resolver rather
+  // than by the relative-path table below.
+  if (agent === 'dsh') return existsSync(dshHome());
   const paths = {
     claude: ['.claude.json', '.claude'],
     codex: ['.codex'],
@@ -2287,6 +2340,43 @@ async function installMcpOnly(agent, bearer) {
  * `adoptExistingClientId`, so a re-run without `--client-id` keeps the header the file already
  * declares (#3772).
  */
+/**
+ * Where dsh keeps its home: `DSH_HOME` wins, `<home>/.dsh` otherwise (#100.4 item 4).
+ *
+ * `DSH_HOME` is a *user* setting, so it may only apply when the install is addressing the real
+ * home. `--home <dir>` means "pretend this directory is the home" — the test suite and the e2e
+ * depend on every write staying inside it. Honouring `DSH_HOME` there wrote the user's real
+ * `~/.dsh/AGENTS.md` from inside a sandbox run (measured 2026-10-30: the suite truncated it to
+ * 35 bytes, and the next message reloaded the broken block).
+ */
+function dshHome(home = HOME) {
+  const real = homedir();
+  if (process.env.DSH_HOME && resolve(home) === resolve(real)) return process.env.DSH_HOME;
+  return join(home, '.dsh');
+}
+
+/**
+ * dsh is a plugin-bundle client, so only half of it is a file target.
+ *
+ * The tools (`mcp__misakanet__*`) come from the `misakanet` plugin bundle, which dsh installs with
+ * its own command — there is no JSON file this installer could write. The rules, however, live in
+ * `$DSH_HOME/AGENTS.md`, and writing them is exactly the manual step the README used to ask for.
+ * So the installer writes the half it can and prints the half it cannot, instead of doing neither
+ * and leaving the user with two steps that do not know about each other.
+ */
+async function installDsh() {
+  const rules = join(dshHome(), 'AGENTS.md');
+  const profile = process.env.DSH_PROFILE || 'web';
+  const manual = `dsh plugin --profile ${profile} add misakanet`;
+  if (!MCP_ONLY) {
+    ok(`dsh：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  } else {
+    skip('dsh：规则块未写（--mcp-only）');
+  }
+  need(`dsh：工具在插件包里，安装器不写这个文件 → 跑 \`${manual}\``
+    + '（不跑就只有规则、没有 mcp__misakanet__* 工具）');
+}
+
 async function installMcode(bearer) {
   const plugin = mcodePluginPath(HOME);
   const existing = readText(plugin);
@@ -2781,6 +2871,23 @@ async function verify() {
       }
     }
   }
+  // dsh: one file, and only half of the client — so the report says which half it can see. The
+  // rules block is our footprint and is checked like every other target's; the tools live in the
+  // plugin's profile, which this process cannot read, and a "complete" that quietly skipped that
+  // would be the false green this whole report exists to avoid (measured 2026-10-30: with the
+  // block deleted, `--verify` still said 安装完整性：完整).
+  if (wantClient('dsh') && detect('dsh')) {
+    const rules = join(dshHome(), 'AGENTS.md');
+    if (!readText(rules).includes(`<!-- ${START} -->`)) {
+      needWrite('dsh', rules,
+        `dsh：规则块没装（${rules}）→ 重跑安装命令`,
+        `dsh：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
+    } else {
+      ok('dsh：规则块已装', 'dsh');
+      skip(`dsh：工具在插件包里，--verify 看不到它 → 跑 \`dsh plugin --profile ${process.env.DSH_PROFILE || 'web'} list\` 复核`,
+        'dsh');
+    }
+  }
   // Version: what is installed, and whether the registry has moved on. Read-only here — the
   // hook owns the periodic nudge (it cannot be a network call in this process's hot path), and
   // `--verify` is an explicit user action, so one lookup is both cheap and expected.
@@ -3130,6 +3237,7 @@ function mcodePluginDirectoryOwnership() {
 
 function uninstall() {
   let hermesRulesRemoved = false;
+  if (stripBlock(join(dshHome(), 'AGENTS.md'))) ok(`移除规则块 → ${join(dshHome(), 'AGENTS.md')}`);
   for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md', '.minimax/AGENTS.md']) {
     if (stripBlock(join(HOME, rel))) {
       ok(`移除规则块 → ${rel}`);
@@ -3771,6 +3879,7 @@ try {
         else if (agent === 'openclaw') await installOpenclaw(bearer);
         else if (agent === 'codewhale') await installCodewhale(bearer);
         else if (agent === 'mcode') await installMcode(bearer);
+        else if (agent === 'dsh') await installDsh();
         else if (MCP_ONLY_TARGETS[agent]) await installMcpOnly(agent, bearer);
         installed += 1;
       } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "MisakaNet failure lessons for your agents: writes an MCP endpoint into each agent config, rules blocks where the client takes one, and a Claude Code hook. At most one anonymous request leaves this machine at install; then only the agent's calls — unless MISAKANET_HOOK_FETCH=1 (off by default) the hook sends the failed call's error text or command.",
   "bin": {
     "misakanet-setup": "bin/misakanet-setup.mjs"