@kira905/dsh-butler-panel 0.9.1 → 0.9.2

package/README.md

@@ -30,7 +30,23 @@
 
 ## 接上你自己的大管家
 
-面板通过四个环境变量找东西，**从高到低**：
+面板找库**分四路，前命中即用**：
+
+| 路 | 来源 | 说明 |
+|---|---|---|
+| ① | `BUTLER_ROOT` / `DSH_BUTLER_LIB_DIR`（还认 `BUTLER_LIB_DIR`） | 你显式指了就以你指的为准，优先级最高 |
+| ② | `<工作区>/tools/dsh-butler/lib` | 工作区约定位置（`DSH_WORKSPACE` 不设时 = `<用户主目录>/DSH`） |
+| ③ | **已安装的 `@kira905/dsh-butler-engine` 包** | 依次试包内 `lib/` → `src/dsh-butler/lib/` → `src/lib/` → `jobs/lib/`。定位包根按「显式 env `DSH_BUTLER_ENGINE_ROOT` → Node 模块解析 → 全局 npm 前缀」三档走 |
+| ④ | 都落空 | 占位 + 一行**可照做**的指引（见下） |
+
+为什么要第 ③ 路：不是每台机器都有「大管家工具目录」——那本来是自己工作区里的东西。
+但 `@kira905/dsh-butler-engine` 是**能装的包**，装上就有同一批库。于是最省事的接法变成：
+
+```powershell
+npm i -g @kira905/dsh-butler-engine
+```
+
+环境变量仍然有用（放在最前面，压过包）：
 
 | 变量 | 含义 | 不设时 |
 |---|---|---|
@@ -38,15 +54,22 @@
 | `DSH_WORKSPACE` | DSH 工作区根（`tools/` 与 `docs/` 所在那层） | `<用户主目录>/DSH` |
 | `DSH_HOME` / `BUTLER_DSH_HOME` | DSH 数据根（会话、看板账本、状态文件） | `~/.dsh` |
 | `DSH_BUTLER_LIB_DIR` | 只覆盖"共享库目录"这一项 | 跟随 `BUTLER_ROOT` |
+| `DSH_BUTLER_ENGINE_ROOT` | 直接点名 engine 包根（装了但找不到时的逃生口） | 自动探测 |
 
 ```powershell
 # 例：工具目录放在你自己的某个工作区下
 $env:DSH_WORKSPACE = '<你的工作区>'
 ```
 
-**接不上会怎样**：面板不会崩。所有依赖那套库的功能都退化成「不可用」并在控制台留一行
-`[butler-panel] 大管家库缺失（…）`。这样设计是因为插件是整棵加载的——任一模块顶层
-`import` 失败会把整个插件树拖死、连带 `dsh web` 起不来，那比"少显示一段"严重得多。
+**接不上会怎样**：面板不会崩。缺的那几段退化成「不可用」，并在控制台留一行**告诉你怎么补**：
+
+```
+[butler-panel] 缺 store.mjs：装 npm i -g @kira905/dsh-butler-engine@^0.5.0，或设 BUTLER_ROOT=<你的大管家工具目录>
+```
+
+（那行里的版本号是读**装在盘上的包**得来的，不是写死的；包完全没装时就不带版本号。）
+这样设计是因为插件是整棵加载的 —— 任一模块顶层 `import` 失败会把整个插件树拖死、
+连带 `dsh web` 起不来，那比"少显示一段"严重得多。
 
 ## 它挂在哪里
 

package/lib/advice-hook.mjs

@@ -23,7 +23,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { pathToFileURL } from 'node:url';
-import { butlerLib } from './butler-root.mjs';
+import { butlerLibPath } from './butler-root.mjs';
 
 /** 本钩子版本（≤ 产品版本，见 lib/version.mjs 的约定）。 */
 export const ADVICE_HOOK_VERSION = '0.1.0';
@@ -35,7 +35,6 @@ export const NO_ADVICE_FLAG = '--no-advice';
 export const ADVICE_LOCK_NAME = 'p5-advice';
 /** 锁 TTL（与 report-advice.mjs 一致）。 */
 export const ADVICE_LOCK_TTL_MS = 180_000;
-const BUTLER_LIB_DIR = butlerLib();
 
 /** 本次运行是否显式关闭 P2.5（argv / env 任一命中即关）。 */
 export function isAdviceDisabled({ argv = process.argv.slice(2), env = process.env } = {}) {
@@ -53,8 +52,8 @@ function resolveHome(env = process.env) {
 
 /** 默认加载器：动态 import butler lib（Windows 下 ESM 不吃绝对路径 → 必须 pathToFileURL）。 */
 async function defaultLoader() {
-  const advice = await import(pathToFileURL(path.join(BUTLER_LIB_DIR, 'advice.mjs')).href);
-  const store = await import(pathToFileURL(path.join(BUTLER_LIB_DIR, 'store.mjs')).href);
+  const advice = await import(pathToFileURL(butlerLibPath('advice.mjs')).href);
+  const store = await import(pathToFileURL(butlerLibPath('store.mjs')).href);
   return { advice, store };
 }
 

package/lib/butler-root.mjs

@@ -5,20 +5,31 @@
 // 为什么需要它：插件部署后落在 `~/.dsh/profiles/web/node_modules/<pkg>/lib/`，
 // 相对路径会解析到 `node_modules/…` 而那里没有大管家工具目录 ⇒ 静态 import 失败会
 // 带崩整个 plugin tree。历史做法是写死 `file:///<绝对路径>` 形式的 URL，能用但把本机目录写进了源码。
-// 本模块把那个绝对前缀换成四个环境变量，默认值退化为「用户主目录下的约定位置」。
+// 本模块把那个绝对前缀换成环境变量，默认值退化为「用户主目录下的约定位置」。
 //
-// 口径（优先级从高到低）：
+// ── 解析顺序（**每一路都要能单独说清**）──────────────────────────────────────
 //
-//   BUTLER_ROOT     大管家工具根（即 `<workspace>/tools/dsh-butler`）
-//   DSH_WORKSPACE   DSH 工作区根（`tools/` 与 `docs/` 所在的那层）
-//   由 home 推导      仅当 DSH_HOME / BUTLER_DSH_HOME 被重定向成 `<root>/.dsh` 形态时取 `<root>`
-//   兜底              `<用户主目录>/DSH`
+//   1. 显式指定                    `DSH_BUTLER_LIB_DIR` / `BUTLER_ROOT`（`BUTLER_LIB_DIR` 亦认）
+//                                  —— 用户明确指了就以他指的为准，优先级最高，行为不变
+//   2. 工作区约定                  `<工作区>/tools/dsh-butler/lib`（工程内既有缺省，保留）
+//   3. npm 包回落（本版新增）        `@kira905/dsh-butler-engine` 包内依次试
+//                                  `lib/` → `src/dsh-butler/lib/` → `src/lib/` → `jobs/lib/`
+//                                  （定位包根见 ./engine-search.mjs：显式 env → 模块解析 → 全局前缀）
+//   4. 全落空                      占位 + **可照做**的一句指引（见 guidanceFor()）
 //
-// 任何一项解析不到真实目录都不会在这里抛错：本模块只负责**算出路径**，
-// 「目录不存在怎么办」由调用方决定（多数检查走 fail-soft，把该段标成「不可探测」）。
+// 为什么要第 3 路：全新机器上不一定有「大管家工具目录」——那本来是个人工作区里的东西。
+// 但 `@kira905/dsh-butler-engine` 是**可安装的包**，装上就有同样的库。没有它时面板只能整片
+// 显示「不可用」；有了它，装个包面板就能出真数据（A-8 第三关）。
+//
+// 🔴 三件不许做的事
+//   · 不许把库代码复制进本包（面板侧不内联一份"最小实现"）—— 只**引用**，不**复制**。
+//   · 不许把「找不到」伪装成成功：每一路都只认**真实存在的文件**。
+//   · 不许跨进程缓存：ESM 有模块缓存，换 env 必须换进程才叫验证（否则是假绿）。
 import os from 'node:os'
+import fs from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { engineLibDirs, engineVersion, engineRoots, ENGINE_PKG } from './engine-search.mjs'
 
 /** DSH 数据根：BUTLER_DSH_HOME > DSH_HOME > ~/.dsh。 */
 export function dshHome() {
@@ -51,7 +62,7 @@ export function butlerRoot() {
 
 /** 大管家共享库目录下的路径。 */
 export function butlerLib(...seg) {
-  return path.join(butlerRoot(), 'lib', ...seg)
+  return path.join(butlerLibSearchDirs()[0] ?? path.join(butlerRoot(), 'lib'), ...seg)
 }
 
 /** 工作区 `tools/` 下的路径（跨工具共享件，例如 dsh-host-rpc / panel-tokens）。 */
@@ -79,41 +90,131 @@ export function asUrl(p) {
   return pathToFileURL(p).href
 }
 
-// 下面四个是给"模块级一次性加载"用的便捷入口：内部就是 path + URL，方便单点替换。
-//
-// ⚠️ 为什么这里要兜底而不是让 import 抛：插件是**整棵加载**的，任一模块顶层 import 失败
-//    会让 plugin tree 挂掉、`dsh web` 起不来。用户机器上可能压根没装大管家工具目录，
-//    那种情况下正确的行为是"面板照常起来、依赖大管家的那几段显示不可用"，
-//    而不是把整个宿主拖死。
-//    所以：只有**找不到模块**（用户没装）才退化成占位，模块有语法错等真错照旧往上抛。
-//    占位对象上任何属性访问都返回一个"调用即报错"的函数，错误信息直接告诉用户该设哪个变量。
+// ── 搜索目录（纯路径，不读文件）────────────────────────────────────────────
+
+function dedupe(dirs) {
+  const out = []
+  const seen = new Set()
+  for (const d of dirs) {
+    if (!d) continue
+    const key = d.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(d)
+  }
+  return out
+}
+
+/** `<butlerRoot>/lib` 的候选目录，按优先级。第一项当「主目录」用（兼容 no-arg 调用）。 */
+export function butlerLibSearchDirs() {
+  const dirs = []
+  // ① 显式指定 —— 优先级最高，与旧版逐字一致
+  const libDir = (process.env.DSH_BUTLER_LIB_DIR ?? '').trim()
+  const legacyLibDir = (process.env.BUTLER_LIB_DIR ?? '').trim()
+  if (libDir) dirs.push(path.resolve(libDir))
+  if (legacyLibDir) dirs.push(path.resolve(legacyLibDir))
+  if ((process.env.BUTLER_ROOT ?? '').trim()) dirs.push(path.join(path.resolve(process.env.BUTLER_ROOT.trim()), 'lib'))
+  // ② 工作区约定（旧版缺省）
+  dirs.push(path.join(workspaceRoot(), 'tools', 'dsh-butler', 'lib'))
+  // ③ npm 包回落
+  dirs.push(...engineLibDirs('butler'))
+  return dedupe(dirs)
+}
+
+/** `<工作区>/tools/lib` 的候选目录。 */
+export function toolLibSearchDirs() {
+  return dedupe([path.join(workspaceRoot(), 'tools', 'lib'), ...engineLibDirs('tool')])
+}
+
+/** 大管家工具根顶层（CLI 脚本）的候选目录。 */
+export function butlerFileSearchDirs() {
+  return dedupe([butlerRoot(), ...engineLibDirs('butlerFile')])
+}
+
+function firstExistingFile(dirs, name) {
+  for (const dir of dirs) {
+    const p = path.join(dir, name)
+    try {
+      if (fs.statSync(p).isFile()) return p
+    } catch { /* 这一档没有 */ }
+  }
+  return null
+}
+
+/**
+ * 某个库文件的真实路径：按 butlerLib 的候选目录顺序找，找不到返回旧版缺省路径
+ * （调用方据此拼错误信息，用户在提示里看到的仍是"你以为该在的地方"）。
+ */
+export function butlerLibPath(name) {
+  return firstExistingFile(butlerLibSearchDirs(), name) ?? path.join(butlerRoot(), 'lib', name)
+}
+
+/** `<工作区>/tools/lib` 版。 */
+export function toolLibPath(name) {
+  return firstExistingFile(toolLibSearchDirs(), name) ?? toolLibDir(name)
+}
+
+/** 大管家工具根顶层版（`butlerFile` 的加载用）。 */
+export function butlerFilePath(name) {
+  return firstExistingFile(butlerFileSearchDirs(), name) ?? butlerFile(name)
+}
+
+/** 诊断用：某文件命中了哪一路（找不到返回 null）。 */
+export function butlerLibHit(name) {
+  return firstExistingFile(butlerLibSearchDirs(), name)
+}
+
+// ── 占位与加载 ─────────────────────────────────────────────────────────────
+
+/**
+ * 降级话术：**可照做**，不是「不可用」三个字。
+ * 版本号取 engine 包的**实际版本**（读不到就退成不带版本的安装命令——不写死一个会过期的号）。
+ */
+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=<你的大管家工具目录>`
+}
+
 function unavailableStub(name) {
-  const msg = `大管家库不可用：${name} —— 请把 BUTLER_ROOT 或 DSH_WORKSPACE 指向你的大管家工具目录（详见 README「接上你自己的大管家」）`;
-  const stub = function () { throw new Error(msg) };
+  const msg = guidanceFor(name)
+  const stub = function () { throw new Error(msg) }
   // 让调用方能在"不触发调用"的前提下认出这是占位（例如 `X = mod.Foo ?? null` 之后再 `new X()`）。
-  Object.defineProperty(stub, 'butlerUnavailable', { value: true, enumerable: false });
+  Object.defineProperty(stub, 'butlerUnavailable', { value: true, enumerable: false })
+  // 排障用：到底找过哪些目录、装没装包（不进错误文本，避免刷屏）
+  Object.defineProperty(stub, 'butlerSearched', {
+    value: { dirs: butlerLibSearchDirs(), engineRoots: engineRoots() },
+    enumerable: false,
+  })
   // `then` 必须显式排除：否则这个对象会被当成 thenable，await / Promise.resolve 会挂住。
-  return new Proxy({}, { get: (_t, k) => (k === 'then' ? undefined : stub) });
+  return new Proxy({}, { get: (_t, k) => (k === 'then' ? undefined : stub) })
 }
 
-const MISSING_CODES = new Set(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ENOENT']);
+const MISSING_CODES = new Set(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ENOENT'])
 
-async function loadOrStub(url, name) {
+async function loadOrStub(resolvePath, name) {
+  const target = resolvePath(name)
+  let exists = false
+  try { exists = fs.statSync(target).isFile() } catch { /* 不存在 */ }
+  if (!exists) {
+    try { console.warn(`[butler-panel] ${guidanceFor(name)}`) } catch { /* 控制台不可用就算了 */ }
+    return unavailableStub(name)
+  }
   try {
-    return await import(url)
+    return await import(asUrl(target))
   } catch (e) {
+    // 文件在、但它自己的依赖缺（例如只搬了半个闭包）——同样降级，不让面板整棵挂掉。
     if (MISSING_CODES.has(e?.code)) {
-      try { console.warn(`[butler-panel] ${msgOf(name)}`) } catch { /* 控制台不可用就算了 */ }
+      try { console.warn(`[butler-panel] ${guidanceFor(name)}（依赖不全：${String(e?.message ?? e).split('\n')[0]}）`) } catch { /* 同上 */ }
       return unavailableStub(name)
     }
     throw e
   }
 }
-function msgOf(name) { return `大管家库缺失（${name}）⇒ 该功能降级为「不可用」` }
 
-export function importButlerLib(name) { return loadOrStub(asUrl(butlerLib(name)), name) }
-export function importToolLib(name) { return loadOrStub(asUrl(toolLibDir(name)), name) }
-export function importButlerFile(name) { return loadOrStub(asUrl(butlerFile(name)), name) }
+export function importButlerLib(name) { return loadOrStub(butlerLibPath, name) }
+export function importToolLib(name) { return loadOrStub(toolLibPath, name) }
+export function importButlerFile(name) { return loadOrStub(butlerFilePath, name) }
 
 /**
  * 状态文件路径解析器：优先用大管家 lib 的 `resolveStatePath`；库不可用时退到**等价的最简形态**

package/lib/engine-search.mjs

@@ -0,0 +1,138 @@
+// dsh-butler-panel / lib/engine-search.mjs
+//
+// 只做一件事：**定位 @kira905/dsh-butler-engine 这个包在哪、它里面有哪些库目录**。
+//
+// 为什么要单独一件：面板里不止一处需要"找库"（butler-root 的加载器、metrics 的环境探测），
+// 而 metrics.mjs 明确承诺自己不 import 面板的业务模块。把这段纯路径逻辑抽成无副作用的
+// 小件，两边都能用，又不把业务耦合带进去。
+//
+// 🔴 为什么不只靠 createRequire：engine 在安装清单里是 **CLI 类型**（`npm i -g`），
+//    落在全局前缀（Windows 是 `%APPDATA%\npm\node_modules`），而面板落在
+//    `~/.dsh/profiles/web/node_modules/`。Node 的模块解析只会从面板所在目录**向上**爬，
+//    爬不到全局前缀 ⇒ 单靠 createRequire 在真实装载形态下必然找不到。
+//    所以这里按「显式指定 → 模块解析 → 全局前缀常见位置」三档走，每档都只读、失败不抛。
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+
+export const ENGINE_PKG = '@kira905/dsh-butler-engine'
+
+/** 各调用方要的"库目录"在包内的候选位置（顺序 = 优先级）。 */
+export const ENGINE_SUBDIRS = {
+  // <butlerRoot>/lib 的镜像：engine 把生产 tools/dsh-butler/lib 放在 src/dsh-butler/lib
+  butler: ['lib', 'src/dsh-butler/lib', 'src/lib', 'jobs/lib'],
+  // <workspace>/tools/lib 的镜像：engine 放在 src/lib
+  tool: ['src/lib', 'lib', 'src/dsh-butler/lib', 'jobs/lib'],
+  // <butlerRoot> 顶层的镜像（CLI 脚本在 src/dsh-butler/，作业脚本在 jobs/）
+  butlerFile: ['src/dsh-butler', 'jobs', 'lib', 'src/dsh-butler/lib'],
+}
+
+const require_ = createRequire(import.meta.url)
+
+/** 从某个入口文件向上爬，找到 name 匹配的 package.json 所在目录。 */
+function pkgRootOf(entry) {
+  if (!entry) return null
+  let dir = path.dirname(entry)
+  for (let i = 0; i < 10; i++) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+      if (j && j.name === ENGINE_PKG) return dir
+    } catch { /* 这一层没有或坏了，继续上溯 */ }
+    const up = path.dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+  return null
+}
+
+/** 全局 npm 前缀下包可能出现的位置（不 spawn npm，只按约定路径猜）。 */
+function globalNodeModules() {
+  const out = []
+  const add = (p) => { if (p && String(p).trim()) out.push(path.resolve(String(p).trim())) }
+
+  const prefix = process.env.npm_config_prefix || process.env.NPM_CONFIG_PREFIX
+  if (prefix) {
+    add(path.join(prefix, 'node_modules'))
+    add(path.join(prefix, 'lib', 'node_modules'))
+  }
+  if (process.env.APPDATA) add(path.join(process.env.APPDATA, 'npm', 'node_modules'))
+  if (process.env.LOCALAPPDATA) add(path.join(process.env.LOCALAPPDATA, 'npm', 'node_modules'))
+
+  // node 自己就在前缀根里时（自定义安装、绿色版、nvm 等）
+  const exeDir = path.dirname(process.execPath)
+  add(path.join(exeDir, 'node_modules'))
+  add(path.join(exeDir, '..', 'lib', 'node_modules'))
+
+  add(path.join(os.homedir(), '.npm-global', 'lib', 'node_modules'))
+  if (process.platform !== 'win32') {
+    add('/usr/local/lib/node_modules')
+    add('/usr/lib/node_modules')
+  }
+  return out
+}
+
+let cachedRoots = null
+
+/**
+ * engine 包根候选（按优先级，已去重、已过滤不存在的）。
+ * 返回 [] = 这台机器上压根没装 engine。
+ */
+export function engineRoots() {
+  if (cachedRoots) return cachedRoots
+  const roots = []
+  const push = (p) => {
+    if (!p) return
+    const abs = path.resolve(p)
+    if (roots.some((x) => x.toLowerCase() === abs.toLowerCase())) return
+    roots.push(abs)
+  }
+
+  // ① 显式指定（用户/测试可钉死；装了但找不到时这也是逃生口）
+  const explicit = (process.env.DSH_BUTLER_ENGINE_ROOT ?? '').trim()
+  if (explicit) push(explicit)
+
+  // ② Node 自己的模块解析（面板与 engine 同树 / 被提升到同一 node_modules 时命中）
+  for (const spec of [`${ENGINE_PKG}/package.json`, ENGINE_PKG]) {
+    try { push(pkgRootOf(require_.resolve(spec))) } catch { /* 这一路走不通就下一路 */ }
+  }
+
+  // ③ 全局前缀（真实装载形态：engine 是 CLI，装到全局）
+  for (const nm of globalNodeModules()) {
+    const cand = path.join(nm, ...ENGINE_PKG.split('/'))
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(cand, 'package.json'), 'utf8'))
+      if (j && j.name === ENGINE_PKG) push(cand)
+    } catch { /* 不在这一档，继续 */ }
+  }
+
+  cachedRoots = roots.filter((r) => fs.existsSync(path.join(r, 'package.json')))
+  return cachedRoots
+}
+
+/** 某个用途下**真实存在**的库目录（绝对路径，按优先级）。 */
+export function engineLibDirs(kind = 'butler') {
+  const subdirs = ENGINE_SUBDIRS[kind] ?? ENGINE_SUBDIRS.butler
+  const out = []
+  for (const root of engineRoots()) {
+    for (const sub of subdirs) {
+      const dir = path.join(root, sub)
+      try { if (fs.statSync(dir).isDirectory()) out.push(dir) } catch { /* 没有这层 */ }
+    }
+  }
+  return out
+}
+
+/** engine 的实际版本号（用于降级话术里给可照做的安装命令）；读不到返回 null。 */
+export function engineVersion() {
+  for (const root of engineRoots()) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+      if (j?.version) return String(j.version)
+    } catch { /* 下一处 */ }
+  }
+  return null
+}
+
+/** 测试用：清掉缓存（换过 env 必须换进程，否则是假绿）。 */
+export function resetEngineCache() { cachedRoots = null }

package/lib/metrics.mjs

@@ -71,7 +71,8 @@
 
 import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { createHash } from 'node:crypto';
+import { createHash } from 'node:crypto';
+import { engineLibDirs } from './engine-search.mjs';
 
 /** 指标模块版本（唯一入口；接口字段名自 A1 冻结后不得改）。 */
 // 0.2.1（2026-09-18 · 施工卡 ⑥-2「面板额度字段」）：`autoActionsToday` **只追加** `quotaGate`
@@ -225,6 +226,9 @@ const BUTLER_LIB_DIRS = [
   (process.env.BUTLER_ROOT ?? '').trim() ? path.join(process.env.BUTLER_ROOT.trim(), 'lib') : null,
   (process.env.DSH_WORKSPACE ?? '').trim() ? path.join(process.env.DSH_WORKSPACE.trim(), 'tools', 'dsh-butler', 'lib') : null,
   path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'dsh-butler', 'lib'),
+  // 全新机器上没有「大管家工具目录」，但可能有已安装的 npm 包（@kira905/dsh-butler-engine）。
+  // 这里只借 engine-search 的**纯路径**能力，不碰任何面板业务模块，本文件的零依赖性质不变。
+  ...engineLibDirs('butler'),
 ].filter(Boolean);
 
 async function tryImport(url) {

package/lib/modules-route.mjs

@@ -11,7 +11,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { butlerLib as butlerLibDir } from './butler-root.mjs';
+import { butlerLibPath } from './butler-root.mjs';
 
 /**
  * 默认 home（DSH 数据根）解析：口径 BUTLER_DSH_HOME > DSH_HOME > ~/.dsh
@@ -27,7 +27,6 @@ export function dshHome() {
   if (override && override.trim()) return path.resolve(override.trim());
   return path.join(os.homedir(), '.dsh');
 }
-const BUTLER_LIB = butlerLibDir();
 
 /** runAction() 第三道闸恒查的 L1 键（与 CLI `module list` 末尾恒定口径同源；lib\autonomy-actions.mjs，位置=dry-run 通道之后）。 */
 export const RUN_ACTION_ALWAYS_KEY = 'p3AutoEnabled';
@@ -66,15 +65,15 @@ let libCache = null;
 /** 动态 import butler 侧 lib（缺失/损坏 → 抛给调用方降级，绝不拖垮面板启动）。 */
 async function butlerLib() {
   if (libCache) return libCache;
-  const mods = await import(pathToFileURL(path.join(BUTLER_LIB, 'autonomy-modules.mjs')).href);
-  const auto = await import(pathToFileURL(path.join(BUTLER_LIB, 'autonomy.mjs')).href);
+  const mods = await import(pathToFileURL(butlerLibPath('autonomy-modules.mjs')).href);
+  const auto = await import(pathToFileURL(butlerLibPath('autonomy.mjs')).href);
   // 🌒 影子视图（卡：V3 批次 1）：缺失不影响模块开关卡本身 → 单独 try，降级为 null
   let shadow = null;
-  try { shadow = await import(pathToFileURL(path.join(BUTLER_LIB, 'shadow-view.mjs')).href); } catch { shadow = null; }
+  try { shadow = await import(pathToFileURL(butlerLibPath('shadow-view.mjs')).href); } catch { shadow = null; }
   // ① 包 P-3/P-5（施工卡 ①-1）：控制室判据底座（**唯一判定入口**）——
   //   缺失/损坏 → 降级为 null（本卡照常渲染既有字段，绝不拖垮面板）。
   let verdict = null;
-  try { verdict = await import(pathToFileURL(path.join(BUTLER_LIB, 'control-room-verdict.mjs')).href); } catch { verdict = null; }
+  try { verdict = await import(pathToFileURL(butlerLibPath('control-room-verdict.mjs')).href); } catch { verdict = null; }
   libCache = { mods, auto, shadow, verdict };
   return libCache;
 }
@@ -218,7 +217,7 @@ export const INFRA_REFUSE_CODE = 'infra-protected';
 /** 拒关留痕（走既有审计哈希链 `lib/audit.mjs`；审计不可用**不阻断**拒关应答）。 */
 async function recordModuleRefusal({ home, id, scope, by, why, source }) {
   try {
-    const m = await import(pathToFileURL(path.join(BUTLER_LIB, 'audit.mjs')).href);
+    const m = await import(pathToFileURL(butlerLibPath('audit.mjs')).href);
     m?.appendAudit?.({ type: 'module-refused', module: id, reason: INFRA_REFUSE_CODE, scope, source, by, why },
       { home, silent: true });
   } catch { /* 审计不可用不影响"拒关"这个保护动作本身 */ }

package/lib/p4-learnings.mjs

@@ -17,7 +17,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 // 【2c · 2c-B5】状态路径统一入口（legacy 期与 path.join(dir, name) 逐字节相同）。
-import { butlerLib, statePathResolver } from './butler-root.mjs';
+import { butlerLibPath, statePathResolver } from './butler-root.mjs';
 const resolveStatePath = await statePathResolver();
 
 export const P4_LEARNINGS_VERSION = '0.1.0';
@@ -39,7 +39,7 @@ let scoreLibCache = null;
 async function loadScoreLib() {
   if (scoreLibCache) return scoreLibCache;
   const { pathToFileURL } = await import('node:url');
-  scoreLibCache = await import(pathToFileURL(path.join(butlerLib(), 'pitfall-score.mjs')).href);
+  scoreLibCache = await import(pathToFileURL(butlerLibPath('pitfall-score.mjs')).href);
   return scoreLibCache;
 }
 

package/lib/shards.mjs

@@ -41,7 +41,7 @@ import { STATE_CACHE_TTL_MS, SHARD_BUDGET_MS, cacheKeyOf, singleFlight, createBu
 import { readPanelSwitches } from './panel-switches.mjs';
 import { collectMetrics } from './metrics.mjs';
 // 【2c · 2c-B5】状态路径统一入口（legacy 期与 path.join(home, name) 逐字节相同）。
-import { butlerLib as butlerLibDir, statePathResolver } from './butler-root.mjs';
+import { butlerLibPath, statePathResolver } from './butler-root.mjs';
 const resolveStatePath = await statePathResolver();
 
 /** 已实现的片名（顺序即文档顺序）。
@@ -96,8 +96,7 @@ export const FEED_ITEM_CAP = 8;
 export const FEED_BYTES_CAP = 5_600;
 /** health 片超时预算（生态面板 HTTP 是固定价，独立于 core 的 1.2s）。 */
 export const HEALTH_BUDGET_MS = 6_000;
-/** butler lib 目录（口径与 state.js 的 BUTLER_LIB_DIR 一致：面板独立可跑，不依赖 tools 树存在）。 */
-const BUTLER_LIB_DIR = (process.env.BUTLER_LIB_DIR ?? '').trim() || butlerLibDir();
+/** butler lib 解析口径：交给 butler-root 的多路回落（显式 → 工作区约定 → npm 包），本文件不再自己拼目录。 */
 
 // ---------------------------------------------------------------------------
 // 片白名单（R1：`?parts=core` 必须**子字段级**可断言；M3 要求 core 明写 sessions.interrupted）
@@ -199,7 +198,7 @@ async function butlerLib(name) {
   if (butlerLibraries.has(name)) return butlerLibraries.get(name);
   let mod = null;
   try {
-    mod = await import(pathToFileURL(path.join(BUTLER_LIB_DIR, name)).href);
+    mod = await import(pathToFileURL(butlerLibPath(name)).href);
   } catch { mod = null; }
   butlerLibraries.set(name, mod);
   return mod;

package/lib/state.js

@@ -18,7 +18,7 @@ import * as eva from './host-adapter.mjs';
 // 会话日志文件名判据 / 「取哪份」取法 —— **生态唯一源**（★2026-09-24 本批统一，见下方 newestSessionLog 上方长注）。
 // 跨包一律走 ./butler-root.mjs 解析（路径由环境变量决定，源码里不留本机绝对目录；
 // 相对 import 会在部署到 profile 后解析成不存在的包 ⇒ 门禁①直接挡）。
-import { importButlerLib, importToolLib, workspaceRoot, butlerLib as butlerLibDir, asUrl, statePathResolver } from './butler-root.mjs';
+import { importButlerLib, importToolLib, workspaceRoot, butlerLibPath, asUrl, statePathResolver } from './butler-root.mjs';
 const { SESSION_FILE_RE, pickSessionFileInDir } = await importToolLib('session-file-name.mjs');
 // 【2c · 2c-B5】状态路径统一入口（legacy 期与 path.join(dshHome(), name) 逐字节相同）。
 const resolveStatePath = await statePathResolver();
@@ -1085,12 +1085,12 @@ const MAINTENANCE_FILE = resolveStatePath('butler-maintenance.json', { home: dsh
 const RESTART_REQUEST_FILE = process.env.BUTLER_RESTART_REQUEST_FILE
   || path.join(process.env.TEMP || os.tmpdir(), 'dsh-guard', 'restart-request.json');
 const AUDIT_DIR = path.join(dshHome(), 'butler-audit');
-const BUTLER_LIB_DIR = butlerLibDir();
 /** 计划任务每分钟一次 → 3 分钟没刷新心跳 = 协调器被停/被拦（验收 6）。 */
 const HEARTBEAT_STALE_MS = 3 * 60 * 1000;
 
+// 库路径统一交给 butler-root 的多路回落（显式指定 → 工作区约定 → 已安装的 npm 包）。
 async function butlerLib(name) {
-  return import(asUrl(path.join(BUTLER_LIB_DIR, name)));
+  return import(asUrl(butlerLibPath(name)));
 }
 function readJsonFile(file, fallback = null) {
   try {

package/package.json

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