@sidady/dsh-steward 0.9.12 → 0.9.14

package/README.md

@@ -1,7 +1,85 @@
 # dsh-steward — 智能管家（体检 + 授权执行）插件
 
-**状态：v0.9.12 已安装并热挂载（体检 + 授权执行 + 对话入口 + 设置项）**
+**状态：v0.9.14 已安装并热挂载（体检 + 授权执行 + 对话入口 + 设置项）**
 
+## v0.9.14（冷启动竞态：路由与工具都注册了，只是没在最合适的那一刻）
+
+### 症状和真正的原因不是同一件事
+
+重启之后面板照旧报 `读取失败: 接口没有挂上（HTTP 404）`。v0.9.13 已经能把这句
+话翻译成人话，但它把原因归给了「热重载」——而这一次是冷启动，热重载的解释
+根本对不上。真正的原因更安静：
+
+`apply()` 里原本是这样拿服务的：
+
+```js
+const webServer = getService(ctx, 'webServer');
+if (webServer && typeof webServer.register === 'function') { ... }
+```
+
+`getService` 只做 `ctx.get(key)` 或 `ctx[key]`，而 **`ctx.get` 在 Cordis 里只能拿到
+那一刻已经 apply 完的服务**。冷启动时 `webServer` 与 `tools` 的 apply 都排在本插件
+之后，于是那一次探测拿到 `null`，整个 `if` 被跳过：前缀路由没注册、两个
+`dsh_steward_*` 工具也没注册。外面的 `try { ... } catch { /* ignore */ }` 是刻意的
+fail-soft（注册失败不该拖垮 boot），代价是**失败完全无声**——面板照常从 manifest
+画出来，然后每个请求都撞在「没有命名路由匹配 → 404」上。
+
+所以这不是「路由写错了」，是「注册发生在错误的时刻」。热重载会是同一个症状，
+但它们是两个不同的病因，v0.9.13 的诊断文案只认识其中一种。
+
+### 改法：等它就绪，再注册
+
+新增 `whenService(ctx, keys, fn)`：优先走 `ctx.inject(keys, cb)`，回调在服务真正
+存在之后才执行；`:root` 上没有 `inject` 时退回旧的一次性探测（行为与从前一致，不会
+更差）。三处注册（`systemPrompt` 段、前缀路由、tools）全部改走它。
+
+- 用 `ctx.inject` 而不是 `export const inject = [...]`，是因为硬 inject 会让本插件
+  成为 **boot 依赖**——它的 apply 一旦抛错，整个 Web UI 起不来。这个插件的第一原则
+  是「不许让面板成为新的崩溃源」，所以宁可延迟注册，也不升级成硬依赖。
+- `ctx.effect` 仍然包在回调里，所以热重载时 dispose 依旧会被正确回收。
+
+### 失败必须能看见
+
+注册结果记在 `wiring.route` 里，`ping` 的返回体多一个字段：
+
+```
+{"ok":true,...,"wiring":{"route":"registered"}}
+```
+
+下次再出现「面板画出来了但每个请求都 404」，只需要看一眼 ping：`registered` 说明
+路由在，问题在别处；`pending` 或 `failed: ...` 直接指到病因。**静默的 fail-soft 是
+这次真正的坑**——比注册失败本身更难查，因为它连一条可搜的日志都不留。
+
+### 这一版钉住的判据
+
+`smoke.mjs` 新增五条静态判据（291 条断言）：必须用 `ctx.inject` 延迟注册；三处注册
+全都走 `whenService`；**旧的裸 `try { const webServer = getService(...)` 写法必须彻底
+消失**；`wiring.route` 要记录成功与失败两种结果；`ping` 要把它带出来。反向验证过：
+把路由那段改回一次性探测，立刻 `289 passed, 2 failed`。
+
+## v0.9.13（路由没挂上时，别只说 HTTP 404）
+
+改插件源码会让宿主热重载：旧 fiber 被销毁，新 fiber 重新跑一遍 `apply()`。
+真机踩到的形态是——重载过后 `apply()` 里那段 `webServer.register({ kind: 'prefix', path: ROUTE_PREFIX })`
+没有接上，面板打开就只剩一行红字 `读取失败: HTTP 404`：bundle 是 enabled + installed，
+源码 `node --check` 全过，`import()` 也正常，只有路由不见了。
+
+`HTTP 404` 这句话的问题不是不准，是**没法行动**：它和「服务端主动回了个 404」长得一模一样，
+而这两种情况的处置完全不同。所以这一版：
+
+1. **认得出来** —— 自己这条路由上的 404 单独成句：说清「面板加载了，但 /api/dsh-steward/ 没注册」，
+   并点名最常见的原因（热重载后旧路由被销毁、新的没接上）。
+2. **说得出怎么办** —— 提示「设置里停用再启用一次」或「直接重启 DSH Web」，两者都真的能修。
+3. **重试一次就够** —— 热重载有一个几百毫秒的窗口，这时路由确实不在；重试一次不会把
+   真正的故障藏起来，也不会让用户对着一个会自动好的状态点按钮。
+4. **别的错误不许挪用这套话** —— 非 404 的失败仍然原样报服务端给的原因，
+   否则「热重载」就成了一个什么都往里装的筐。
+
+五条断言全部是**静态判据**（读 `lib/client.js` 自己的源码），并且反向验证过：把
+`response.status === 404 && tries === 0` 改成 `if (false)`，`285 passed / 1 failed`。
+
+> 顺带记一条运维经验：这个状态下**只有重启/重挂**能修，改代码不会修好它。
+> 而 `plugin_manager set_bundle enabled:false` → `enabled:true` 就是重挂。
 ## v0.9.12（配色：从「自造一套蓝」改成 baseline 的六个 accent）
 
 面板里原本散着 12 处私有颜色：`rgba(90,159,212,.14)` 这种自造的蓝、`#e05555` 这种自造的红、

package/lib/client.js

@@ -1,5 +1,5 @@
 /**
- * dsh-steward · client entry — v0.9.12 (model-mode conversational entry + L1 briefing;
+ * dsh-steward · client entry — v0.9.14 (model-mode conversational entry + L1 briefing;
  * ChatBar rebuilt as a mature chat composer: one rounded input bar, mode chip on the
  * left, round send button on the right, settings panel below the bar;
  * v0.7.5 collapse: a collapsed group lists EVERY peer as a two-line summary row
@@ -119,7 +119,8 @@ window.__ModuleLoader__.load({
     function timeoutFor(action) {
       return SLOW_ACTIONS[action] || DEFAULT_TIMEOUT_MS;
     }
-    async function call(action, extra) {
+    async function call(action, extra, attempt) {
+      const tries = typeof attempt === 'number' ? attempt : 0;
       const name = action || 'report';
       const budget = timeoutFor(name);
       const controller = typeof AbortController === 'function' ? new AbortController() : null;
@@ -145,7 +146,24 @@ window.__ModuleLoader__.load({
         if (timer) clearTimeout(timer);
       }
       let data;
-      try { data = await response.json(); } catch { throw new Error('HTTP ' + response.status); }
+      try { data = await response.json(); } catch { data = null; }
+      // v0.9.13: a 404 on our OWN route is a different failure from a 404 the
+      // server sent on purpose. It means this plugin's fiber is loaded (the
+      // panel rendered) but its route is not mounted. v0.9.14: there are TWO
+      // causes and the earlier wording only named the first — a host hot-reload
+      // disposes the old fiber, AND a cold boot can have webServer apply after
+      // this plugin, which is what the deferred registration now handles.
+      if (response.status === 404 && tries === 0) {
+        await new Promise((r) => setTimeout(r, 700));
+        return call(action, extra, tries + 1);
+      }
+      if (response.status === 404) {
+        throw new Error('接口没有挂上（HTTP 404）——面板加载了，但 /api/dsh-steward/ 这段路由没注册。'
+          + '两种常见原因：宿主热重载（改了插件文件，旧路由被销毁、新的没接上），'
+          + '或冷启动时 webServer 比插件晚就绪。'
+          + '在设置里把这个插件停用再启用一次通常就能恢复；也可以重启 DSH Web。'
+          + '恢复后 ping 会带 wiring.route，值是 registered 就说明路由真的挂上了。');
+      }
       if (!response.ok || !data || data.ok !== true) {
         throw new Error((data && data.error) || 'HTTP ' + response.status);
       }

package/lib/index.js

@@ -65,6 +65,48 @@ function getService(ctx, key) {
   return null;
 }
 
+// What the deferred wiring actually achieved. Reported by ping so "the panel
+// draws but every request 404s" stops being indistinguishable from "fine".
+const wiring = { route: 'pending', via: {} };
+
+/**
+ * v0.9.14: run `fn` once the named services are live.
+ *
+ * getService() only sees services that are ALREADY active at the moment of the
+ * call. On a cold boot `webServer` and `tools` activate after this plugin, so a
+ * one-shot lookup returns null and every registration is skipped — silently,
+ * because each block is wrapped in a fail-soft try/catch. The symptom is exactly
+ * what was reported: the panel draws itself (its client bundle comes from the
+ * manifest) while the route and both tools were never registered, so each
+ * request answered 404 and every dsh_steward_* tool was absent.
+ *
+ * ctx.inject() is the documented optional-access path: it defers the callback
+ * until the services exist. Unlike a hard `export const inject` it does not make
+ * this bundle a boot dependency.
+ */
+function whenService(ctx, keys, fn) {
+  let injected = false;
+  try {
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(keys, (scoped) => {
+        wiring.via[keys.join(',')] = 'inject';
+        try { fn(scoped || ctx); } catch (e) {
+          try { if (typeof ctx.logger?.warn === 'function') ctx.logger.warn('[dsh-steward] deferred setup failed (' + keys.join(',') + '): ' + String(e && e.message || e)); } catch { /* noop */ }
+        }
+      });
+      injected = true;
+    }
+  } catch (e) {
+    try { if (typeof ctx.logger?.warn === 'function') ctx.logger.warn('[dsh-steward] ctx.inject unavailable: ' + String(e && e.message || e)); } catch { /* noop */ }
+  }
+  if (injected) return true;
+  // Fallback for a ctx without inject(): the old best-effort one-shot lookup.
+  try {
+    if (getService(ctx, keys[0])) { wiring.via[keys.join(',')] = 'one-shot'; fn(ctx); return true; }
+  } catch { /* nothing live yet — stays inert, as before */ }
+  return false;
+}
+
 function sendJson(res, status, value) {
   try {
     const body = Buffer.from(JSON.stringify(value));
@@ -451,7 +493,7 @@ export function apply(ctx) {
   }
 
   async function run(action, payload) {
-    if (action === 'ping') return { ok: true, plugin: name, version: pkgVersion(), readOnly: false, hub: true };
+    if (action === 'ping') return { ok: true, plugin: name, version: pkgVersion(), readOnly: false, hub: true, wiring: { ...wiring } };
     // v0.8.0 settings: 只读设置页需要的一切（值 + 范围 + 为什么），以及一次写入。
     if (action === 'settings') {
       await loadSettings();
@@ -643,7 +685,7 @@ export function apply(ctx) {
   // @changfenhuang/dsh-genui/lib/index.js:7772 ({name, order, text}, order via
   // getSectionOrder). Guarded: if the service or getSectionOrder is missing we
   // skip entirely (探针先行 red line: never guess, never endanger boot).
-  try {
+  whenService(ctx, ['systemPrompt'], () => {
     const sp = getService(ctx, 'systemPrompt');
     if (sp && typeof sp.section === 'function' && typeof sp.getSectionOrder === 'function') {
       ctx.effect(() => {
@@ -659,15 +701,17 @@ export function apply(ctx) {
         }
       }, 'dsh-steward: prompt section');
     }
-  } catch { /* systemPrompt lookup failed — passive mode, panel red dot only */ }
+  });
 
-  // 2) Host prefix route (panel + same-origin callers).
-  try {
+  // 2) Host prefix route (panel + same-origin callers). Deferred until the
+  // service exists: on a cold boot webServer activates after this plugin, and a
+  // one-shot lookup silently registered nothing (the reported 404).
+  whenService(ctx, ['webServer'], () => {
     const webServer = getService(ctx, 'webServer');
     if (webServer && typeof webServer.register === 'function') {
       ctx.effect(() => {
         try {
-          return webServer.register({
+          const dispose = webServer.register({
             kind: 'prefix',
             path: ROUTE_PREFIX,
             handler: async (req, res) => {
@@ -688,17 +732,20 @@ export function apply(ctx) {
               }
             },
           });
+          wiring.route = 'registered';
+          return dispose;
         } catch (e) {
+          wiring.route = 'failed: ' + String(e && e.message || e);
           // Contained: a route registration failure must NOT fail the boot fiber.
           try { if (typeof ctx.logger?.warn === 'function') ctx.logger.warn('[dsh-steward] route registration skipped: ' + String(e && e.message || e)); } catch { /* noop */ }
           return undefined;
         }
       }, 'dsh-steward: routes');
     }
-  } catch { /* webServer lookup failed — ignore */ }
+  });
 
-  // 3) Read-only health tool (kept from v0.1).
-  try {
+  // 3) Read-only health tool (kept from v0.1). Same cold-boot race, same fix.
+  whenService(ctx, ['tools'], () => {
     const tools = getService(ctx, 'tools');
     if (tools && typeof tools.register === 'function') {
       ctx.effect(() => {
@@ -774,7 +821,7 @@ export function apply(ctx) {
         }
       }, 'dsh-steward: act tool');
     }
-  } catch { /* tools lookup failed — ignore */ }
+  });
 }
 
 export default apply;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidady/dsh-steward",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "type": "module",
   "description": "Guardian for DeepSeek Harness: a read-only health check (boot crashes, backup freshness, config drift, workspace growth, plugin updates, host-version compat, model availability) plus an explicitly authorized action layer (plan → single-use fingerprint → confirm → audit) covering cache cleaning, encrypted volatile-data backups, plugin enable/disable, knowledge capture, finding mute, and switching the default model.",
   "keywords": [

package/smoke.mjs

@@ -1376,6 +1376,57 @@ check('the cause survives into finding data for the panel', !!liveCrash && liveC
   check("washes and rings derive from an accent", mixUses >= 6, String(mixUses));
   check("the only saturated tokens are the six accents", /accentStability/.test(src) && /accentInfo/.test(src));
 }
+
+// — v0.9.13: 面板自己的路由没挂上时，不许只说「HTTP 404」 —
+{
+  // 真机形态：改了插件源码触发宿主热重载，旧 fiber 被销毁、新 fiber 的路由
+  // 没接上，面板只剩一行「读取失败: HTTP 404」。用户无法判断这是接口没挂、
+  // 还是请求本身出错。这一组钉住三件事：认得出来、说得出怎么办、只重试一次。
+  const clientSrc = fs.readFileSync(path.join(here, 'lib', 'client.js'), 'utf8');
+  const callBody = clientSrc.slice(clientSrc.indexOf('async function call('), clientSrc.indexOf('function PanelIcon'));
+
+  check('a 404 on our own route is distinguished from a plain HTTP failure',
+    /response\.status === 404/.test(callBody) && /接口没有挂上/.test(callBody));
+  check('the 404 message names the hot-reload cause and the way out',
+    /热重载/.test(callBody) && /停用再启用|重启 DSH Web/.test(callBody));
+  check('the retry is bounded — one attempt, then it reports',
+    /tries === 0/.test(callBody) && /call\(action, extra, tries \+ 1\)/.test(callBody));
+  check('a generic failure still reports the server error verbatim',
+    /\(data && data\.error\) \|\| 'HTTP ' \+ response\.status/.test(callBody));
+  // 反向判据：不许把任何非 2xx 都说成「热重载」，那会把真正的服务端错误藏掉。
+  check('the hot-reload wording is gated on 404, not on every non-2xx',
+    !/接口没有挂上/.test(callBody.split('response.status === 404')[0]));
+}
+// — v0.9.14: 冷启动竞态 —— 服务没就绪时不许把注册整段跳过 —
+{
+  // 真机形态：重启（不是热重载）后面板照样 404。原因不是路由写错了，而是
+  // apply() 里用 ctx.get('webServer') 一次性探测：冷启动时 webServer 与 tools
+  // 都比本插件晚 apply，那一次探测拿到 null，于是 if (webServer && ...) 整段
+  // 跳过，路由与两个工具都没注册 —— 而每段外面都包了 fail-soft try/catch，
+  // 所以只 warn 一行，面板与工具都静默消失。
+  const idxSrc = fs.readFileSync(path.join(here, 'lib', 'index.js'), 'utf8');
+
+  check('the plugin defers to ctx.inject instead of a one-shot lookup',
+    /ctx\.inject\(keys,/.test(idxSrc) && /function whenService\(/.test(idxSrc));
+  check('every service-backed registration goes through whenService',
+    (idxSrc.match(/whenService\(ctx, \['/g) || []).length >= 3);
+  // 反向判据：旧的裸探测写法必须彻底消失，否则冷启动仍会静默跳过。
+  check('no registration is left behind a bare try/getService probe',
+    !/try \{\n\s*const webServer = getService\(/.test(idxSrc)
+      && !/try \{\n\s*const tools = getService\(/.test(idxSrc)
+      && !/try \{\n\s*const sp = getService\(/.test(idxSrc));
+  // 静默失败是这次真正的病因：说得出「挂上了没有」比「应该挂上」有用。
+  check('the wiring outcome is recorded, not just logged',
+    /wiring\.route = 'registered'/.test(idxSrc) && /wiring\.route = 'failed: '/.test(idxSrc));
+  check('ping reports the wiring outcome so a 404 is diagnosable',
+    /wiring: \{ \.\.\.wiring \}/.test(idxSrc));
+  // 走的是哪条路也要记：inject 与一次性探测在冷启动下行为完全不同，
+  // 只看 route=registered 无法区分「真的等了」和「碰巧那次就绪了」。
+  check('the wiring path records whether inject was used',
+    /wiring\.via\[keys\.join\(','\)\] = 'inject'/.test(idxSrc)
+      && /wiring\.via\[keys\.join\(','\)\] = 'one-shot'/.test(idxSrc));
+}
+
 console.log('');
 console.log(`RESULT: ${pass} passed, ${fail} failed`);
 process.exit(fail === 0 ? 0 : 1);