dsh-mobile-plugin 0.1.57 → 0.1.58

package/README.md

@@ -79,12 +79,43 @@ DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
   市场代劳重启 DSH。
 - **装完/更新完要完整重启 DSH**：插件是 profile 层的 cordis bundle，进程起来时依赖树就定死了。
   市场会把这件事报成 `restartRequired`，页面上有对应提示与按钮。
-- 发版：抬版本号（`node scripts/bump-version.mjs`）后 `npm publish`。插件不再自带发布脚本，
-  也没有「中转 OTA」这条分发源了。
+- 如果「设置 → 移动端 → 打开配置页面」打不开、页面吐一段 `panel_missing` JSON：那段文案会
+  写清是**哪一种**读不到 —— 「装完没重启」（旧实例还挂在这次安装删掉的那个目录上，最常见）、
+  「装了老版本」（0.1.47 及更早还没有这一页）还是「真没构建」（源码树里才会遇到）。三种解法
+  不同，别照着「没重启」的现场去跑 React 构建。同一句话也会进宿主 stderr。
 - 从前那套的教训记在这里：热更新只换宿主侧的实现代，**换不掉设置菜单那一半**（渲染器直接从
   安装目录读它），于是出现过「更新报成功、界面一动不动」，重启 DSH、重启 sidecar 都没用。
   现在只有一条更新路径，这类「哪一半是旧的」不再存在。
 
+### 发版流程（自己发一版更新）
+
+1. **抬版本号**：`node scripts/bump-version.mjs`（三段各 `0..999`）。
+2. **改过 `React/` 就先重建面板**：`cd React && pnpm run build`。产物 `lib/panel/index.html`
+   是**提交物**，要和源码一起提交 —— 忘了重建，发出去的就是旧页面，而仓库里没有任何东西能
+   替你发现（守卫只比字节形状，不比新旧）。
+3. **自检**：`npm test`（其中 `panel-artifact` 管产物形状与「读不到时报什么」，
+   `publish-payload` 管发布清单收得住每个会被加载的文件）；`npm pack --dry-run` 扫一眼发了什么。
+4. **发布**：`npm publish`。
+5. **核对**：`npm view dsh-mobile-plugin version`。
+6. **到机器上更新**：DSH → 设置 → 插件 里更新，**然后完整重启 DSH**。
+
+**发布这一步现在要你现场过二次验证**（2026-10 起，别以为是配错了）：
+
+- `npm publish` 会打印一条 `https://www.npmjs.com/auth/cli/…` 链接（或直接开浏览器），用账号
+  绑定的**安全密钥**确认一下，它自己接着把包发出去。
+- 所以这一步**必须能打开 www.npmjs.com**：机房/代理出口 IP 会被它的反机器人拦成 403
+  （页面写「访问暂时受限」并带上你的 IP）。换个节点或直连再发。
+- npm 已经关掉了「命令行建号」和「验证器 App（TOTP）」两条路：建号只能在网页上做，2FA 只能挂
+  安全密钥。这两件事上试命令是白费时间，认它就行。
+- 想少点一次确认，可以建一把「允许绕过 2FA」的细粒度令牌少输几次验证：
+  `npm token create --bypass-2fa --packages dsh-mobile-plugin --packages-and-scopes-permission read-write --expires 90`
+  （**最长 90 天**）。代价：这类令牌 **2027-01 起不能再直接发布**，到期或到点都得回到上面
+  那条交互式路径。
+- 还有个死结记在这里：令牌不能指向**还不存在**的包（会报
+  `You do not have access to the requested package(s)`），所以**第一版只能用浏览器验证发**，
+  令牌是「包已经存在之后」才有的便利。
+
+
 插件没有 GUI 外壳，配置入口是插件注册在 `webServer` 上的**仅限本机访问**（`localOnly` 守卫）
 的 HTTP 端点。`host.js` 启动后，其 `webServer.port` 就是下面 URL 里的 `<port>`
 （无头部署下固定 `3080`）：

package/lib/routes/control-plane.js

@@ -35,13 +35,19 @@ const MAX_DESKTOP_READ_IDS = 200;
 /**
  * 面板页（`React/` 那份 React 源码构建成的单文件 HTML）在包里的位置。
  *
- * 用 `__dirname` 而不是包根：控制面路由住在「实现代」里（`lib/.live/<releaseId>/…`），
- * 所以这一份 HTML 跟着实现代一起换代 —— 改版式走 `/update/apply` 就生效，不用重装、
- * 不用重启 DSH。这正是把设置界面从客户端半边（`lib/client.js`，不可热替换）搬过来的原因。
+ * 用 `__dirname` 而不是包根，是为了「谁跟着这份路由一起走」：HTML 是**提交物**，和
+ * `lib/` 在同一份安装里，装哪个版本就带哪个版本的页面。
+ *
+ * 这段注释过去写的是「控制面路由住在实现代 `lib/.live/<releaseId>/` 里，改版式不用重装」——
+ * 那套「稳定外壳 + 可热替换的代」随插件 OTA 在 2026-10 一起删了（A5-02）。现在改版式只有
+ * 一条路：`React/` 里重建 → 提交产物 → 发新版本 → 市场里更新 → 完整重启 DSH。
  */
 const PANEL_FILE = path.join(__dirname, '..', 'panel', 'index.html');
 
-/** 按 mtime 缓存：换代之后路径变了、内容变了，缓存自然失效，不必手工清。 */
+/** 插件包根（`<pkg>/lib/routes` 往上两级）：诊断时读它的 `package.json` 与 `React/`。 */
+const PACKAGE_DIR = path.join(__dirname, '..', '..');
+
+/** 按 mtime 缓存：文件被换掉之后内容变了，缓存自然失效，不必手工清。 */
 let panelCache = { file: '', mtime: -1, html: '' };
 
 function panelHtml() {
@@ -56,6 +62,59 @@ function panelHtml() {
   }
 }
 
+/**
+ * 面板读不到时，说清楚**是哪一种读不到**。
+ *
+ * 这条是给「装了但打不开」的现场用的。过去这里只有一句「去 `React/` 里跑一次
+ * pnpm run build」，那是**开发树**才遇得到的情况；装到别人机器上时它几乎总是另外两件事：
+ *
+ *  1. **安装目录整个不见了**（2026-10-10 实测现场）：在插件市场里装/更新过、DSH 还没完整
+ *     重启，跑着的仍是旧实例，而旧实例所在的 pnpm 目录已经被这次安装删掉了 —— 代码在内存里，
+ *     所以路由照常响应，`fs` 一读就 ENOENT，面板页于是吐一段 JSON。解法是**重启 DSH**，
+ *     不是去跑构建。
+ *  2. **这份安装里根本没有产物**：0.1.47 及更早的版本还没有这一页（`files` 白名单当时
+ *     没收 `lib/` 下的 html），老包里点开就是这条。解法是**更新到当前版本**。
+ *
+ * 两件事的解法完全不同，所以分开报，并把路径与版本一起带上 —— 下次看到这段报错，一眼就知道
+ * 该重启还是该升级。三种情形由 `test/panel-artifact.test.cjs` 钉住。
+ *
+ * @param {{panelFile?: string, packageDir?: string}} [paths] 只给测试喂临时目录用；运行时走默认路径
+ * @returns {{reason: 'install-gone'|'artifact-missing'|'unreadable', message: string}}
+ */
+function panelDiagnosis(paths) {
+  const panelFile = paths?.panelFile ?? PANEL_FILE;
+  const packageDir = paths?.packageDir ?? PACKAGE_DIR;
+  let version = '';
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8')).version || '';
+  } catch {}
+  const versionOf = version ? `v${version}` : '版本读不到';
+
+  if (!fs.existsSync(packageDir)) {
+    return {
+      reason: 'install-gone',
+      message: `插件的安装目录已经不在了（${packageDir}）：多半是刚在插件市场里装/更新过、但 DSH 还没完整重启 —— 跑着的旧实例还挂在这次安装删掉的那个目录上。完整重启 DSH 即可恢复。`,
+    };
+  }
+  if (!fs.existsSync(panelFile)) {
+    // 有没有 `React/src` 是「源码树 vs 装进来的包」唯一可靠的判据：`files` 不收 React/。
+    const sourceTree = fs.existsSync(path.join(packageDir, 'React', 'src'));
+    return {
+      reason: 'artifact-missing',
+      message: sourceTree
+        ? `面板产物还没构建（${panelFile}）：在 dsh-mobile-plugin/React 里跑一次 pnpm run build（产物是提交物，构建完要跟源码一起提交）。`
+        : `这份安装（${versionOf}）里没有面板产物（${panelFile}）：0.1.47 及更早的版本还没有这一页。在 DSH 的插件市场里更新到当前版本，再完整重启 DSH。`,
+    };
+  }
+  let cause = '';
+  try {
+    fs.readFileSync(panelFile);
+  } catch (error) {
+    cause = `：${error && error.message ? error.message : error}`;
+  }
+  return { reason: 'unreadable', message: `面板产物读不出来（${panelFile}，${versionOf}）${cause}` };
+}
+
 /**
  * 面板页的绝对地址，给客户端半边那个「打开配置页面」的链接用。
  *
@@ -130,8 +189,13 @@ function registerControlPlaneRoutes(deps) {
   // 而局域网与中转那两条链路本来就不该看到它（它们带 dsh_pair/dsh_lan 凭据，会被挡掉）。
   const servePanel = (res) => {
     const html = panelHtml();
-    if (!html) return sendJson(res, 500, { ok: false, error: { code: 'panel_missing', message: '面板页面还没构建：在 dsh-mobile-plugin/React 里跑一次 pnpm run build' } });
-    return sendHtml(res, 200, html);
+    if (html) return sendHtml(res, 200, html);
+    // 读不到就别只说「还没构建」：装进来的包几乎从不是这个原因，而是「装完没重启」或
+    // 「装了老版本」（见 panelDiagnosis 的注释）。原因也写进宿主 stderr —— 页面上的
+    // JSON 只有点开那个人看得见，而这类故障通常是在别人的机器上被报出来的。
+    const diagnosis = panelDiagnosis();
+    process.stderr.write(`[dsh-mobile-plugin] panel unavailable (${diagnosis.reason}) ${PANEL_FILE}: ${diagnosis.message}\n`);
+    return sendJson(res, 500, { ok: false, error: { code: 'panel_missing', reason: diagnosis.reason, message: diagnosis.message, path: PANEL_FILE } });
   };
   registerRoute({ kind: 'exact', path: '/api/relay/panel', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
   registerRoute({ kind: 'exact', path: '/api/relay/panel/setup', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
@@ -308,4 +372,6 @@ function registerControlPlaneRoutes(deps) {
   }) })
 }
 
-module.exports = { registerControlPlaneRoutes };
+// `panelDiagnosis` 一并导出，只为让 test/panel-artifact.test.cjs 能拿临时目录跑那三条分支：
+// 三种「读不到」的文案分别对应「重启 / 升级 / 构建」，它们混起来就是这个 bug 的原样。
+module.exports = { registerControlPlaneRoutes, panelDiagnosis };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.57",
+  "version": "0.1.58",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",