dsh-mobile-plugin 0.1.62 → 0.1.64

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WNLUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,9 +10,28 @@ Electron 运行时**，`node host.js` 即可独立运行。
 
 设备级实时兼容出口：`GET /api/mobile/v1/events/stream`（Bearer token）以 SSE 转发宿主 `events.mux` 的所有设备事件。每帧包装为 `{ type: "device/event", version: 1, eventId, sessionId?, rpcId?, payload }`；`payload` 保留原 mux 负载，旧的 `/session/stream` 与 relay 协议不变。`session/event` 的 `eventId` 为 `${sessionId}:${event.seq}`，其他帧使用连接内序号。工作区变更是否可见取决于宿主 mux 是否发布对应帧；当前插件没有额外伪造工作区事件。
 
+## 仓库与发布
+
+本仓库是插件的**公开发布仓库**，仓库根就是包根：别人从这里读代码，也从这里核对这份代码的说法。
+
+开发和 App 客户端、中转服务器放在一起进行（一个私有 monorepo），所以这里的提交历史从拆分那天开始，
+不是项目历史 —— 每次发版，把同一次改动一起推到这里。
+
+- **仓库地址要指回本仓库**：`package.json` 的 `repository` 字段是 npm 包与插件列表条目之间的唯一关联
+  （列表侧从注册表自动采集，条目里不许手写 `npm:`）。改了它要等下一次 `npm publish` 才会体现在注册表上。
+- **要被插件列表（awesome-dsh-plugin）收录**：往那个仓库提一个数据文件
+  `data/plugins/<owner>__<repo>.yml` 就行，**一个文件即全部投稿**；`description.en` 必填，分类用 `remote`。
+  硬门槛是 `package.json` 里声明 `dsh.bundle`（只声明 `dsh.client` 会被 CI 拒）、仓库创建满 1 天、
+  以及本仓库打了 `dsh-plugin` topic。那条「满 1 天」的检查**会自己转绿**（列表侧每 6 小时重跑一次），
+  当天看到红不用重提、也不用关了重开。
+- **截图**：市场详情页要图，就在 `package.json` 旁边放一份 `screenshots.json`，列 1-8 张**本仓库内**的图片路径
+  （相对路径不能跳出仓库；绝对地址只收 GitHub 托管的 https）。不声明也行，市场会自己从本 README 里找图。
+- **描述会被对着代码核**：条目里写的每个数字和 API 名字都要在代码里找得到。夸大是唯一会被打回的原因 ——
+  分类选得不准不会，维护者会直接改。
+
 ## 无头部署
 
-部署到 Linux 服务器（无桌面环境）时的要点，完整 runbook 见仓库根 [`../README.md`](../README.md) 的「服务器部署」。
+部署到 Linux 服务器（无桌面环境）时的要点如下。
 
 **目录布局不能漏掉凭据库。** 设备凭据库 `dsh-mobile-credentials` 就在本包目录内部（发布时它仍是独立的一个包，装进来后嵌在插件目录里），代码用包内相对路径引用它：
 
@@ -117,6 +136,7 @@ DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
   （页面写「访问暂时受限」并带上你的 IP）。换个节点或直连再发。
 - npm 已经关掉了「命令行建号」和「验证器 App（TOTP）」两条路：建号只能在网页上做，2FA 只能挂
   安全密钥。这两件事上试命令是白费时间，认它就行。
+- **别指望用「绕过 2FA」的令牌跳掉上面这一下**（2026-10-11 实测）：换上这把令牌之后 `npm whoami` 能过，但写操作照样要求交互式验证（拿 `npm dist-tag add` 试的），而 npm 2026-07-31 的公告说这类令牌 2027-01 起连直接发布也会失去。要自动化发布得迁到 trusted publishing（OIDC）或 staged publishing，本项目的发布是人在开发机上发，这两条都不顺手。
 - 想少点一次确认，可以建一把「允许绕过 2FA」的细粒度令牌少输几次验证：
   `npm token create --bypass-2fa --packages dsh-mobile-plugin --packages-and-scopes-permission read-write --expires 90`
   （**最长 90 天**）。代价：这类令牌 **2027-01 起不能再直接发布**，到期或到点都得回到上面

package/lib/http/routing.js

@@ -63,10 +63,17 @@ const readJson = (req) => readJsonBody(req, 256 * 1024).then(body => body || {})
  *
  * @param {object} ctx 插件 ctx，透传给 handler
  * @param {(req: object) => boolean} authorized 移动 token 校验，由调用方注入
+ * @param {() => void} [note] 通过 token 校验之后叫一声：宿主用它记「手机来过」的时刻，
+ *   引导最后一页据此说「手机已经连上了」。**只在校验通过之后叫**，401 那条不算——
+ *   否则随便谁打一下也能把面板骗成「连上了」。
  * @returns {(handler: (ctx: object, req: object, res: object) => Promise<unknown>) => (req: object, res: object) => Promise<unknown>}
  */
-const createGuarded = (ctx, authorized) => (handler) => async (req, res) => {
+const createGuarded = (ctx, authorized, note = null) => (handler) => async (req, res) => {
   if (!authorized(req)) return sendJson(res, 401, { ok: false, error: { code: 'unauthorized', message: '缺少或无效的移动 token' } })
+  if (note) {
+    // 记账本身绝不能影响请求结果：它坏了也只是面板少一个确认。
+    try { note() } catch { /* 忽略 */ }
+  }
   try { await handler(ctx, req, res) } catch (error) {
     sendJson(res, 500, { ok: false, error: { code: 'internal', message: String(error?.message || error) } })
   }

package/lib/impl.js

@@ -24,7 +24,7 @@ const { authorized } = require('./mobile/auth.js')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
-const { lanUrls, lanCandidates } = require('./relay/lan-network.cjs')
+const { lanUrls, advertisedCandidates } = require('./relay/lan-network.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -32,6 +32,8 @@ const { createPreviewService } = require('./relay/preview.js')
 // 入口按两条盘上布局分别找（嵌在插件包内 / 与插件包同级），见 shared/credentials-entry.js。
 const credentials = require('./shared/credentials-entry.js').credentialsEntry()
 const { createApiProxy } = require('./mobile/host-bridge.js')
+// 「手机上最近来过没有」：守卫记、控制面状态读。单独一个模块，装配层只转交。
+const activity = require('./mobile/activity.cjs')
 const { installAutoArchive } = require('./auto-archive.cjs')
 const { registerSessionCleanupTool } = require('./session-cleanup.cjs')
 const { activeGuard } = require('./host-guard.cjs')
@@ -147,7 +149,7 @@ function createConfigStore(state) {
 
 function pairingPayload(state, lanPort) {
   const port = Number.isInteger(lanPort) ? lanPort : state.lanPort
-  const candidates = state.lanEnabled ? safeLanCandidates(port) : []
+  const candidates = state.lanEnabled ? advertisedCandidates(port) : []
   const urls = candidates.map(candidate => candidate.url).filter(Boolean)
   const relayUrl = state.relayUrl || ''
   const payload = {
@@ -168,17 +170,9 @@ function pairingPayload(state, lanPort) {
   }
 }
 
-// 上报给 App 的局域网候选地址。除了 `lanUrls` 里的首个地址，App 还会记住整份
-// 候选列表，换网卡/切网络后依次重试，所以这里尽力给全（`lanInterfaces` 已按
-// 物理网卡优先级排序并剔除 docker/veth/vmnet 这类虚拟接口）。
-function safeLanCandidates(port) {
-  try {
-    const list = lanCandidates(port)
-    return Array.isArray(list) ? list : []
-  } catch {
-    return []
-  }
-}
+// 上报给 App 的候选地址（私网优先、没有私网才退公网）住在 `./relay/lan-network.cjs`
+// 的 `advertisedCandidates`：那是地址策略，不是装配。这里只把它转交给三处消费点。
+// 「手机上最近来过没有」同理，住在 `./mobile/activity.cjs`（守卫记、控制面状态读）。
 
 /**
  * 运行时是否自带 `@deepseek-ai/dsh-host-apiproxy`（即 `api-gateway` 那个入口）。
@@ -340,13 +334,15 @@ function apply(ctx) {
     getLanPortAdjusted: () => lanPortAdjusted,
     pairingPayload,
     restartSidecar,
+    // 「手机上最近来过没有」——控制面状态里补给面板用（见 ./mobile/activity.cjs）。
+    mobileActivity: activity.snapshot,
     // 桌面端「我读过了」那条路由（/api/relay/desktop-read）要清掉宿主侧的完成提醒，
     // 需要插件 ctx 才能拿到按设备隔离的状态表。
     ctx,
   })
 
 
-  const guarded = createGuarded(ctx, authorized)
+  const guarded = createGuarded(ctx, authorized, activity.note)
 
   // 内置浏览器预览的宿主端：手机按端口在它自己的环回上监听，把内置浏览器写下的原始
   // 字节通过 WebSocket 送到这里，这里与 `127.0.0.1:<port>` 对搬。
@@ -387,7 +383,8 @@ function apply(ctx) {
     // 一进来就 ReferenceError。同一个 apply() 里给 createStatusView 传的是
     // `sidecarLifecycle.getSnapshot`，两处不一致才让这个笔误活了下来。
     getSidecarSnapshot: sidecarLifecycle.getSnapshot,
-    safeLanCandidates,
+    // 移动端路由表那边叫它「局域网候选」，取的是同一份私网优先的清单。
+    safeLanCandidates: advertisedCandidates,
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口
   })
   ctx.effect(() => {

package/lib/mobile/activity.cjs

@@ -0,0 +1,28 @@
+'use strict'
+
+/**
+ * 「手机上最近来过没有」—— 一个时间戳，别的什么都没有。
+ *
+ * 移动端守卫每放行一个带有效 token 的请求就叫一次 `note()`（见 `../http/routing.js`
+ * 的 `createGuarded`，**401 那条不算**），控制面把 `snapshot()` 补进本机状态给面板读：
+ * 引导最后一页靠它把「等手机扫码」变成真结论，而不是一个永远转下去的圈。
+ *
+ * 为什么单独一个文件：装配层 `lib/impl.js` 有行数上限（`test/assembly-layer.test.cjs`
+ * 钉着），而这份状态既不属于装配、也不属于路由表。放在模块作用域就够 —— 一个进程就是
+ * 一个宿主，插件的代被换掉时这个数跟着重置，换代之后的第一部手机再来一次就会重新记上，
+ * 正是我们要的语义。
+ */
+
+let lastMobileAt = 0
+
+/** 记一次「手机来过」。守卫里调用；异常一律吞掉——记账坏了也只是面板少一个确认。 */
+function note() {
+  lastMobileAt = Date.now()
+}
+
+/** 面板读的快照。`0` = 从来没来过。 */
+function snapshot() {
+  return { lastMobileAt }
+}
+
+module.exports = { note, snapshot }