@kira905/dsh-butler-panel 0.9.5 → 0.9.6

package/README.md

@@ -17,7 +17,7 @@
 > npm i @kira905/dsh-butler-panel
 > # 或者装进某个 profile 后重启 dsh，侧边栏底部会多一个「大管家」入口
 > ```
-> 装完**先设一个变量**告诉它你的大管家在哪（见下一节）——不设也能起来，但大部分卡片会显示「不可用」。
+> 装完**先设一个变量**告诉它你的大管家在哪（见下一节）——不设也能起来，但大部分卡片会显示「不可探测」。
 
 > ### 它不附带什么（先看清楚，省得装完失望）
 >
@@ -61,10 +61,10 @@ npm i -g @kira905/dsh-butler-engine
 $env:DSH_WORKSPACE = '<你的工作区>'
 ```
 
-**接不上会怎样**：面板不会崩。缺的那几段退化成「不可用」，并在控制台留一行**告诉你怎么补**：
+**接不上会怎样**：面板不会崩。缺的那几段退化成「不可探测」，并在控制台留一行**告诉你怎么补**：
 
 ```
-[butler-panel] 缺 store.mjs：装 npm i -g @kira905/dsh-butler-engine@^0.5.0，或设 BUTLER_ROOT=<你的大管家工具目录>
+[butler-panel] 缺 store.mjs：装 npm i -g @kira905/dsh-butler-engine@^0.5.0，或设 BUTLER_ROOT=<你的大管家工具目录>，或设 DSH_WORKSPACE=<你的 DSH 工作区（tools/ 与 docs/ 所在那层）>
 ```
 
 （那行里的版本号是读**装在盘上的包**得来的，不是写死的；包完全没装时就不带版本号。）

package/lib/butler-root.mjs

@@ -173,7 +173,11 @@ export function butlerLibHit(name) {
 export function guidanceFor(name) {
   const v = engineVersion()
   const install = v ? `npm i -g ${ENGINE_PKG}@^${v}` : `npm i -g ${ENGINE_PKG}`
-  return `缺 ${name}：装 ${install}，或设 BUTLER_ROOT=<你的大管家工具目录>`
+  // 出路按 README 变量表的**顺位**给全：① 装可安装的包 ② 显式 BUTLER_ROOT ③ DSH_WORKSPACE（工作区根，
+  //   解析 `<工作区>/tools/dsh-butler/lib` 的第一顺位）。0.9.6 补 ③：原来只给前两条，用户把
+  //   DSH_WORKSPACE 指错时，这条日志对着他"工作区"这件事一个字都没提。
+  return `缺 ${name}：装 ${install}，或设 BUTLER_ROOT=<你的大管家工具目录>，`
+    + `或设 DSH_WORKSPACE=<你的 DSH 工作区（tools/ 与 docs/ 所在那层）>`
 }
 
 function unavailableStub(name) {

package/lib/client.js

@@ -1209,11 +1209,27 @@ function makePanelUI(cfg) {
 			zone.appendChild(groupTitle("🛑 模块开关（熔断 · L2）"));
 			const rows = mm.modules ?? [];
 			if (!rows.length) {
-				zone.appendChild(healthCard("🛑 模块开关", "不可用", "h-gray", [
-					["状态", "读取失败：" + (mm.error ?? mm.reason ?? "未知")],
-					["常见原因", "面板刚部署但 dsh 还没重启（GET /modules 返回 404）→ 重启后本卡自动恢复"],
-					["兜底", "关/开也可用 CLI：node <大管家目录>/butler-autonomy-cli.mjs module list"]
-				]));
+				// 【0.9.6 · 2026-11-09】归因必须**拆两句**：`Cannot find module …` ≠ `GET /modules 返回 404`。
+				//   前者 = **工作区 / 大管家目录指错**（DSH_WORKSPACE 或 BUTLER_ROOT 没指到那棵树），
+				//   后者才是"面板刚部署但 dsh 还没重启"。0.9.5 及以前把两种混成一句"面板刚部署还没重启"⇒
+				//   接口其实回了 200、只是 body 里是 Cannot find module，照那句话去重启 = 白折腾一轮。
+				//   兜底同理：只给"装 engine 包 + 设 BUTLER_ROOT"漏掉了 README 变量表里第一顺位的 DSH_WORKSPACE。
+				const errText = String(mm.error ?? mm.reason ?? "未知");
+				const is404 = /\b404\b/.test(errText) && !/Cannot find module/i.test(errText);
+				// 实际去找的那个路径（Node 的 ERR_MODULE_NOT_FOUND 消息自带）—— 有就并排显示，没有就退成库文件名
+				const missPath = (errText.match(/Cannot find module\s*['"]([^'"]+)['"]/i) ?? [])[1] ?? null;
+				const lines = [["状态", "读取失败：" + errText]];
+				if (is404) {
+					lines.push(["常见原因", "面板刚部署但 dsh 还没重启（GET /modules 返回 404）→ 重启后本卡自动恢复"]);
+				} else {
+					lines.push(["常见原因", "找不到 " + (missPath ?? "大管家共享库（autonomy-modules.mjs）") + "：多为工作区或大管家目录指错"]);
+					lines.push(["工作区", "DSH_WORKSPACE=<你的 DSH 工作区（tools/ 与 docs/ 所在那层）>"
+						+ (missPath ? "，当前按此解析到 " + missPath : "")]);
+					lines.push(["或", "BUTLER_ROOT=<大管家工具目录（即 <工作区>/tools/dsh-butler 那层）>"]);
+					lines.push(["生效", "改完需重启 DSH 才生效"]);
+				}
+				lines.push(["兜底", "关/开也可用 CLI：node <大管家目录>/butler-autonomy-cli.mjs module list"]);
+				zone.appendChild(healthCard("🛑 模块开关", "不可用", "h-gray", lines));
 				return zone;
 			}
 			const off = rows.filter((x) => x.enabled !== true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kira905/dsh-butler-panel",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "大管家的可视化面板：在 DSH 侧边栏看今天该看什么（结论 / 待处理 / 资产 / 流水 / 健康），只读为主；另带 P5 写入守门人（可挂可摘）。",
   "type": "module",
   "main": "lib/index.js",