dsh-in-hand 1.7.0 → 1.7.1

package/README.md

@@ -109,11 +109,12 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/chat/page?...` | JSON | 往更早翻会话历史 |
 | `/taskwatch/chat/stream?sessionId=` | SSE | 跟随一个会话：开场快照 + 增量事件 + 逐字输出 |
 | `/taskwatch/chat/queue?sessionId=` | JSON | 该会话未领取的消息：`items`（下一轮队列，可重排）与 `steering`（已插到本回合下一步） |
+| `/taskwatch/entries` | JSON | 双入口清单：`{entries:[{kind:'remote'\|'lan',label,url,current}]}`；没配 `publicUrl` 时只有局域网一条 |
 | `/taskwatch/manifest.webmanifest` | JSON | PWA manifest |
 | `/taskwatch/sw.js` | JS | service worker |
 | `/taskwatch/icon-192.png` · `/taskwatch/icon-512.png` | PNG | 图标 |
 
-写（`POST`）—— **只有这 6 条**：
+写（`POST`）—— 只有这 6 条对话入口，外加一条不写宿主状态的换路票据：
 
 | 路径 | 请求体 | 说明 |
 |---|---|---|
@@ -123,9 +124,11 @@ DSH 的 Web GUI 没有内置鉴权，而默认 preset 往往是 `danger-full-acc
 | `/taskwatch/chat/create` | `{}` 或 `{workspace}` | 新建会话；`workspace` 必须命中 `/taskwatch/chat/workspaces` 列出的路径 |
 | `/taskwatch/chat/model` | `{sessionId,provider,model}` | 切换该会话使用的模型 |
 | `/taskwatch/chat/queue/reorder` | `{sessionId,ids:[...]}` | 重排下一轮队列；`ids` 必须是当前队列的完整 id 列表 |
+| `/taskwatch/ticket` | `{to:'remote'\|'lan'}` | 签发 60 秒、一次性的换路票据；只在内存里放一张纸条，不碰会话 / 文件 / 配置。没配 `publicUrl` 时远端请求回 `409 no-public-entry` |
 
 全部注册在 `ctx.webServer` 上，不代理 DSH 自身的 `/api`，也不转发任意路径。
-写入口就只有上面 6 条 —— 契约测试会**正面清点**路由表，增删都会让构建失败
+写入口就只有上面 6 条对话入口 + 1 条换路票据 —— 契约测试会**正面清点**路由表，
+新增路由必须在只读 / 对话 / 非对话写三张白名单里显式归类，漏一个就让构建失败
 （早先那条断言写的是"源码里不出现 `method === 'POST'`"。加了 5 个写路由之后它
 照样通过，是条假绿灯：它证明的是"没这么写"，不是"没有这个能力"）。
 
@@ -459,21 +462,41 @@ PWA 外壳由中继本地提供（而不是转发上游），这样它不随上
 换路等于换了一个**源**（`https://…` ↔ `http://192.168.x.x:3099`），而浏览器的 cookie 是
 **按源隔离**的 —— 在远端那条路上换到的 cookie，到了局域网这条路等于不存在。
 
-所以页面点切换时，先向当前这条路的中继要一张凭据：
+所以页面点切换时，先向当前这条路的**宿主**（中继，或插件宿主本身）要一张凭据：
 
-1. `POST /taskwatch/ticket`（带令牌）→ 中继返回另一条路的 URL，末尾带一次性 `?t=…`；
+1. `POST /taskwatch/ticket`（中继上要带令牌）→ 返回另一条路的 URL，末尾带一次性 `?t=…`；
 2. 手机跳过去，中继兑换这张票：**60 秒有效、兑换即作废、重放无效**，同时给那条路种下
    cookie；
 3. 于是不用重新输那 6 位配对码。
 
-这三个接口都在中继侧，**中继不在本仓库**：`GET /taskwatch/entries`（入口清单与当前入口）、
-`POST /taskwatch/ticket`（换路凭据）、`GET /taskwatch/upstream-health`（上游体检）。
-详细的实现与部署文档在中继仓库 **`dsh-in-hand-relay`**（该仓库尚未创建，此处只写仓库名）。
-中继没升级时，页面上的胶囊不会出现，其余功能不受影响。
+**v1.7.1 起，前两条插件宿主也自己实现了**（同一套语义）：`GET /taskwatch/entries`
+回答「现在有哪几条路」，`POST /taskwatch/ticket` 给一张 60 秒、用后即焚的票据。
+所以从宿主页面（例如 `http://127.0.0.1:52676/taskwatch`）点「去远端」不再拿到 405 / 404。
+`GET /taskwatch/upstream-health` 仍只有中继实现；宿主页面拿到它的 404 时按「未知」处理，
+并停掉探测 —— **不会**把「没有体检接口」误判成「这条路断了」。
+
+公网地址只来自插件配置项 `publicUrl`（也支持环境变量 `DSH_TASKWATCH_PUBLIC_URL`），
+代码里不写死任何域名：
+
+```yaml
+- insert:
+    - id: dsh-in-hand
+      name: dsh-in-hand
+      config:
+        publicUrl: https://dsh.example.com
+```
+
+没配就只报局域网入口；`ticket` 的远端请求明确回 `409 no-public-entry`。宿主这层仍然
+不做令牌校验（401 由中继负责），但票据是写路由，所以和中继的写路由同一套门禁：
+`POST` + `application/json` + 同源（`Origin` / `Sec-Fetch-Site`）校验。
+
+页面侧遇到这两条接口的 **404 / 405** 会进入**静态降级**：不重试、不弹错，胶囊按
+「只有一个入口」隐藏；设置 / 任务详情里留一行说明与一个手动「去远端」链接
+（上次成功的地址记在 `localStorage['tw-remote-url']`）。500 / 502 / 网络错误只提示一次
+（同一句 30 秒内不重复弹），不会变成重试风暴。
 
-> 注：上面「在外网 / 手机上访问」一节描述的是只转发读路径的只读中继；实际的中继同时
-> 承载 `/taskwatch/chat/*` 的写入口（见上面的路由表）和本节这三个双入口接口。中继代码
-> 不在本仓库。
+> 中继那边另有独立实现，见中继仓库 `dsh-in-hand-relay`（该仓库尚未创建，此处只写仓库名）。
+> 中继没升级时，页面在宿主上仍能正常用，只是没有远端切换。
 
 ### 502 排查
 

package/lib/index.js

@@ -8,14 +8,16 @@
  * 采集面：会话（运行/空闲、最后活动、activeJobs）、后台任务 jobs、
  * 子代理树、目标轮次与阻塞、工作流阶段、等待审批/提问。
  *
- * 只读：不提供任何写操作、不接受请求体、不代理 DSH 自身的 /api。
+ * 只读为主：除对话接口外不写宿主状态、不代理 DSH 自身的 /api。唯一的例外是
+ * 换路票据（POST /taskwatch/ticket）—— 它只在进程内的短命 Map 里放一张 60 秒的
+ * 纸条，不碰会话、文件或配置，见下方「双入口」一节。
  *
  * 静态资源（PWA）都挂在 /taskwatch/ 之下，service worker 的作用域也限定为
  * /taskwatch —— 绝不允许它有机会拦截主 GUI 的请求。
  */
 import { readFileSync, statSync } from 'node:fs'
-import { createHash, randomUUID } from 'node:crypto'
-import { homedir } from 'node:os'
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { homedir, networkInterfaces } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 // 交付文件的解析与安全边界都在 files.js —— 白名单、穿越防护、类型白名单需要能被
@@ -149,6 +151,117 @@ const why = (e) => (e && e.message ? String(e.message) : String(e))
 
 const ENV_ASSIGN = /^\$env:[A-Za-z_][A-Za-z0-9_]*\s*=/i
 
+// ── 双入口：入口清单与一次性换路票据 ────────────────────────────────────────
+//
+// 背景（2026-10-21，v1.7.1 修的真实故障）：页面在插件宿主上打开时，点「去远端」
+// 会打 POST /taskwatch/ticket 与 GET /taskwatch/entries。这两个接口原先**只有中继
+// 实现**，宿主没有：实测宿主回 405 / 404，页面拿不到 url，探测循环每 12 秒再试一次，
+// 于是在手机上看就是"点了去远端就一直报错"。
+//
+// 现在宿主按中继的语义补齐这两条；公网地址只从配置项 publicUrl 来，**绝不写死域名**。
+// 没配就只报价局域网入口，ticket 明确回 409 no-public-entry。
+//
+// 鉴权边界不变：宿主这层不做令牌校验（和中继的分工见 README），但 ticket 是**写**路由，
+// 所以和中继的写路由一样要求 POST + application/json（跨站表单发不出这个 content-type，
+// 天然需要 preflight，而宿主不应答 CORS 预检），另加一道 Origin / Sec-Fetch-Site 校验。
+export const TICKET_TTL_MS = 60 * 1000
+const TICKET_MAX = 256
+
+/** 公网入口只接受纯 origin（https://host[:port]），带路径的一律当作没配 ——
+ *  否则 302 的 Location 是根绝对路径，和子路径部署对不上，切换会静默跳到错地方。 */
+export function normalizePublicUrl(raw) {
+  const text = typeof raw === 'string' ? raw.trim().replace(/\/+$/, '') : ''
+  if (!text) return ''
+  try {
+    const parsed = new URL(text)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return ''
+    if (!parsed.hostname) return ''
+    if (parsed.pathname && parsed.pathname !== '/') return ''
+    return parsed.origin
+  } catch {
+    return ''
+  }
+}
+
+/** 局域网 IPv4 地址。虚拟网卡（WSL / Hyper-V / docker）不算"手机能连的入口"，
+ *  否则入口清单里会出现一个手机永远打不开的地址 —— 那比不显示更糟。 */
+const VIRTUAL_IFACE = /vEthernet|Hyper-V|WSL|VMware|VirtualBox|Loopback|docker|Bluetooth|TAP-/i
+export function lanAddresses(ifaces, includeVirtual = false) {
+  const table = ifaces && typeof ifaces === 'object' ? ifaces : networkInterfaces()
+  const out = []
+  for (const name of Object.keys(table)) {
+    if (!includeVirtual && VIRTUAL_IFACE.test(name)) continue
+    for (const addr of table[name] || []) {
+      if (!addr || addr.internal) continue
+      if (addr.family !== 'IPv4' && addr.family !== 4) continue
+      const ip = asText(addr.address)
+      if (ip) out.push({ iface: name, ip })
+    }
+  }
+  return out
+}
+
+/** 票据存储：60 秒、一次性。单独抽出来的原因是"过期"要能被测试钉住 ——
+ *  真等 60 秒的测试不会有人跑，而"只删不校验过期"是这类实现最常见的漏洞。 */
+export function createTicketStore({ ttlMs = TICKET_TTL_MS, now = Date.now } = {}) {
+  const tickets = new Map()
+  return {
+    mint() {
+      const at = now()
+      for (const [key, exp] of tickets) if (exp <= at) tickets.delete(key)
+      // 突发时丢最早的一张：票据只有 60 秒寿命，超出上限的多半是重试风暴的残留。
+      while (tickets.size >= TICKET_MAX) {
+        const oldest = tickets.keys().next().value
+        if (oldest === undefined) break
+        tickets.delete(oldest)
+      }
+      const ticket = randomBytes(18).toString('base64url')
+      tickets.set(ticket, at + ttlMs)
+      return ticket
+    },
+    /** 命中即删 —— 无论是否过期，同一张票据第二次兑换一律无效。 */
+    redeem(ticket) {
+      const key = asText(ticket)
+      if (!key) return false
+      const exp = tickets.get(key)
+      if (exp === undefined) return false
+      tickets.delete(key)
+      return exp > now()
+    },
+    get size() { return tickets.size },
+  }
+}
+
+/** 写路由的跨站门禁：显式声明 cross-site 的直接拒；带 Origin 的必须与 Host 同源。
+ *  没有 Origin 的（curl、非浏览器客户端）放行 —— 与"宿主不做令牌校验"的边界一致，
+ *  这里只负责挡住浏览器里的跨站页面。 */
+function isCrossSite(req) {
+  const headers = (req && req.headers) || {}
+  if (String(headers['sec-fetch-site'] || '').toLowerCase() === 'cross-site') return true
+  const origin = asText(headers.origin)
+  if (!origin) return false
+  let originHost = ''
+  try { originHost = new URL(origin).host.toLowerCase() } catch { return true }
+  const host = asText(headers.host).toLowerCase()
+  return Boolean(host) && originHost !== host
+}
+
+function hostOnly(value) {
+  return asText(value).toLowerCase().replace(/:\d+$/, '')
+}
+
+function requestHost(req) {
+  return hostOnly(req && req.headers && req.headers.host)
+}
+
+/** 端口取自请求的 Host 头 —— 这样同一个插件在任意端口上都报得对，不需要写死 52676。 */
+function requestPort(req) {
+  const m = /:(\d+)$/.exec(asText(req && req.headers && req.headers.host))
+  if (!m) return ''
+  const port = Number(m[1])
+  return Number.isFinite(port) && port > 0 && port < 65536 ? String(port) : ''
+}
+
 /** 后台任务的 label 常是多行 shell 命令（含纯环境变量赋值行），折成一行可读文本。 */
 function cleanLabel(raw) {
   const all = asText(raw).split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
@@ -170,7 +283,7 @@ function safe(fn, fallback, errors, label) {
   }
 }
 
-export function apply(ctx) {
+export function apply(ctx, config) {
   const jobsSvc = ctx.get('jobs')
   const agentsSvc = ctx.get('agents')
   const sessionsSvc = ctx.get('sessions')
@@ -1733,10 +1846,198 @@ export function apply(ctx) {
       }), 'in-hand: chat model route')
     }
 
+    // ---- 双入口（远端 / 局域网）--------------------------------------------
+    //
+    // 与 taskwatch-relay 的 /taskwatch/entries、/taskwatch/ticket 同一套语义：
+    // 入口清单说明"现在有哪几条路"，ticket 给一张 60 秒、一次性、用后即焚的通行证。
+    // 差别只有一个：宿主自己不做鉴权，所以兑换后的 Set-Cookie 只是与中继同形的
+    // "换路已完成"标记，不承担授权（授权仍由中继那层负责）。
+    //
+    // 2026-10-21（v1.7.1）：这两条原先**只有中继实现**，宿主没有 —— 页面从宿主加载时
+    // 点「去远端」拿到 405/404，拿不到 url 又每 12 秒重试一次，就是"点了就一直报错"。
+    const settings = config && typeof config === 'object' ? config : {}
+    // 公网地址只从配置来：插件配置项 publicUrl，其次环境变量（与 DSH_TASKWATCH_ROOTS
+    // 同一习惯）。没有配置就只报局域网入口 —— 代码里绝不写死任何域名。
+    const publicUrl = normalizePublicUrl(
+      asText(settings.publicUrl) || asText(process.env.DSH_TASKWATCH_PUBLIC_URL),
+    )
+    const tickets = createTicketStore()
+    const routeJson = (res, status, obj) =>
+      send(res, status, 'application/json; charset=utf-8', JSON.stringify(obj))
+
+    /** 入口清单。current 用布尔标在每条上（新契约）；同时保留中继的
+     *  remote / lan / current 字段，好让同一份 page.html 在两种外壳下都能读。 */
+    function entryList(req) {
+      const host = requestHost(req)
+      const port = requestPort(req)
+      const remoteHost = publicUrl ? hostOnly(new URL(publicUrl).host) : ''
+      const isRemote = Boolean(remoteHost) && host === remoteHost
+      const lan = lanAddresses()
+      const lanUrls = lan.map((a) => 'http://' + a.ip + (port ? ':' + port : '') + '/taskwatch')
+      const lanCurrent = lan.findIndex((a) => a.ip === host)
+      const entries = []
+      if (publicUrl) {
+        entries.push({
+          kind: 'remote',
+          label: '远端（公网）',
+          url: publicUrl + '/taskwatch',
+          current: isRemote,
+        })
+      }
+      lanUrls.forEach((url, i) => {
+        // 本机回环访问时没有哪条局域网地址"等于"当前地址，但它们连的是同一个服务，
+        // 所以把第一条标成当前 —— 只影响胶囊文案，不影响任何跳转。
+        const current = !isRemote && (lanCurrent >= 0 ? i === lanCurrent : i === 0)
+        entries.push({ kind: 'lan', label: '局域网 · ' + lan[i].ip, url, current })
+      })
+      return { entries, remote: publicUrl, lan: lanUrls, current: isRemote ? 'remote' : 'lan' }
+    }
+
+    // ticket 的请求体上限比对话接口还小：这里只该有一个 {"to":"remote"}。
+    function readTicketBody(req) {
+      return new Promise((resolve, reject) => {
+        let size = 0
+        const chunks = []
+        req.on('data', (chunk) => {
+          size += chunk.length
+          if (size > 1024) {
+            reject(new Error('请求体过大'))
+            try { req.destroy() } catch { /* 已断开 */ }
+            return
+          }
+          chunks.push(chunk)
+        })
+        req.on('end', () => {
+          try {
+            const raw = Buffer.concat(chunks).toString('utf8')
+            const parsed = raw ? JSON.parse(raw) : {}
+            resolve(parsed && typeof parsed === 'object' ? parsed : {})
+          } catch (e) { reject(e) }
+        })
+        req.on('error', reject)
+      })
+    }
+
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/taskwatch/entries',
+      handler: (req, res) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+          res.setHeader('allow', 'GET, HEAD')
+          routeJson(res, 405, { ok: false, code: 'method-not-allowed', error: '只接受 GET' })
+          return
+        }
+        const view = entryList(req)
+        routeJson(res, 200, {
+          ok: true,
+          entries: view.entries,
+          // 中继那套字段（页面旧逻辑仍读它们；新逻辑读 entries）
+          remote: view.remote,
+          lan: view.lan,
+          current: view.current,
+        })
+      },
+    }), 'in-hand: entries route')
+
+    // 换路票据：写路由，沿用中继写路由的门禁 —— POST + application/json + 同源。
+    // 宿主不校验令牌（和中继的分工），但绝不能让任意网页用表单 POST 触发一次跳转。
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/taskwatch/ticket',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          res.setHeader('allow', 'POST')
+          routeJson(res, 405, { ok: false, code: 'method-not-allowed', error: '只接受 POST' })
+          return
+        }
+        if (isCrossSite(req)) {
+          routeJson(res, 403, { ok: false, code: 'cross-site', error: '禁止跨站触发换路' })
+          return
+        }
+        const type = String(req.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase()
+        if (type !== 'application/json') {
+          routeJson(res, 415, { ok: false, code: 'unsupported-media-type', error: '请求必须使用 application/json' })
+          return
+        }
+        let want = 'lan'
+        try {
+          const body = await readTicketBody(req)
+          if (asText(body.to) === 'remote') want = 'remote'
+        } catch {
+          routeJson(res, 400, { ok: false, code: 'bad-request', error: '请求体不合法' })
+          return
+        }
+        if (want === 'remote') {
+          if (!publicUrl) {
+            routeJson(res, 409, {
+              ok: false,
+              code: 'no-public-entry',
+              error: '还没有配置公网入口（插件配置项 publicUrl），这里只能走局域网',
+            })
+            return
+          }
+          const ticket = tickets.mint()
+          routeJson(res, 200, {
+            ok: true,
+            to: 'remote',
+            url: publicUrl + '/taskwatch?t=' + ticket,
+            expiresInMs: TICKET_TTL_MS,
+          })
+          return
+        }
+        const lan = lanAddresses()
+        if (!lan.length) {
+          routeJson(res, 409, {
+            ok: false,
+            code: 'no-lan-entry',
+            error: '没有局域网地址（网卡没连上 Wi-Fi？）',
+          })
+          return
+        }
+        // 和中继一样优先挑与请求方同网段的那条，否则第一条。
+        const peer = String((req.socket && req.socket.remoteAddress) || '').replace(/^::ffff:/, '')
+        const net = (ip) => ip.split('.').slice(0, 3).join('.')
+        const pick = lan.find((a) => net(a.ip) === net(peer)) || lan[0]
+        const port = requestPort(req)
+        const ticket = tickets.mint()
+        routeJson(res, 200, {
+          ok: true,
+          to: 'lan',
+          address: pick.ip,
+          iface: pick.iface,
+          url: 'http://' + pick.ip + (port ? ':' + port : '') + '/taskwatch?t=' + ticket,
+          expiresInMs: TICKET_TTL_MS,
+        })
+      },
+    }), 'in-hand: ticket route')
+
+    // 页面外壳。带 ?t= 时先兑换票据：命中 → 302 到 /taskwatch 并种一张换路标记 cookie
+    // （与中继同形）；未知/过期 → 401，和中继在换路凭据无效时的选择保持一致。
+    // 一次性在这里落地：redeem 命中即删，手机上的"后退"再进来不会重放。
     ctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/taskwatch',
-      handler: (req, res) => send(res, 200, 'text/html; charset=utf-8', readPage()),
+      handler: (req, res) => {
+        let ticket = ''
+        try { ticket = new URL(req.url || '/', 'http://127.0.0.1').searchParams.get('t') || '' } catch { ticket = '' }
+        if (ticket) {
+          if (!tickets.redeem(ticket)) {
+            send(res, 401, 'text/plain; charset=utf-8', '换路凭据无效或已过期，请再点一次切换。\n')
+            return
+          }
+          try {
+            res.writeHead(302, {
+              location: '/taskwatch',
+              // 宿主不鉴权，这张 cookie 只是"换路已完成"的标记，不承担授权。
+              'set-cookie': 'tw-route=remote; Path=/taskwatch; HttpOnly; SameSite=Lax; Max-Age=2592000',
+              'cache-control': 'no-store',
+            })
+            res.end()
+          } catch { /* 已断开 */ }
+          return
+        }
+        send(res, 200, 'text/html; charset=utf-8', readPage())
+      },
     }), 'in-hand: page route')
 
     ctx.effect(() => webServer.register({

package/lib/page.html

@@ -573,6 +573,20 @@ main{
 
 .note{font-size:var(--fs-2);color:var(--faint);text-align:center;padding:var(--sp-2) var(--sp-4)}
 
+/* 双入口的静态降级说明（2026-10-21，v1.7.1）。
+   页面由插件宿主提供、宿主没有中继的换路接口时，这里只留一句说明 + 一个手动回跳链接；
+   链接的 padding/margin 是让 44px 的命中区不把这一行撑高（视觉仍是一行）。 */
+.route-note{
+  margin:var(--sp-2) 0;padding:var(--sp-2) var(--sp-3);text-align:left;line-height:1.65;
+  color:var(--faint);font-size:var(--fs-2);background:color-mix(in srgb,currentColor 6%,transparent);
+  border:1px solid color-mix(in srgb,currentColor 16%,transparent);
+  border-radius:var(--dsw-radius-sm);overflow-wrap:anywhere;
+}
+.route-note a{
+  color:var(--accent);text-decoration:underline;text-underline-offset:2px;
+  display:inline-block;padding:12px 2px;margin:-12px 2px;
+}
+
 /* ── 输入区 ─────────────────────────────────────────────────────────── */
 footer{
   flex:0 0 auto;background:var(--panel);border-top:1px solid var(--line);
@@ -3436,6 +3450,12 @@ function bindSheetClose(){
   for (var i = 0; i < xs.length; i++) xs[i].addEventListener('click', closeSheet)
 }
 
+// 双入口的静态降级说明由页面末尾那段独立脚本提供（window.twRouteNote）：
+// 只在「宿主没有中继换路接口」时返回一行，其余时候是空串。
+function routeNote(){
+  try { return (window.twRouteNote && window.twRouteNote()) || '' } catch (e) { return '' }
+}
+
 function openCapability(kind){
   var title = kind === 'plugins' ? '插件' : '自动化'
   var h = sheetHead(title)
@@ -3465,7 +3485,7 @@ async function openSessions(){
   catch (e) { openSheet(sheetHead('会话') + '<div class="note">读取失败：' + esc(e.message) + '</div>'); bindSheetClose(); return }
   if (d && d.error) { openSheet(sheetHead('会话') + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
   S.sessions = (d && d.sessions) || []
-  var h = sheetHead('会话', S.sessions.length)
+  var h = sheetHead('会话', S.sessions.length) + routeNote()
   h += '<label class="sheet-search"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="10.8" cy="10.8" r="6.4"></circle><path d="m16 16 4.2 4.2"></path></svg><input id="sessionSearch" type="search" placeholder="搜索会话或工作区" autocomplete="off" aria-label="搜索会话或工作区"></label>'
   // 显示设置：字号三档 + 只看对话。放在会话列表上方，打开「对话」就能看到。
   var fcur = document.documentElement.getAttribute('data-font') || 'medium'
@@ -3640,15 +3660,15 @@ function kv(k, v){
 async function openStatus(){
   var stBtn = document.getElementById('status')
   if (stBtn) stBtn.setAttribute('aria-expanded', 'true')
-  openSheet(sheetHead('任务详情') + '<div class="note">读取中…</div>')
+  openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取中…</div>')
   var d = lastData
   if (!d || d.error) {
     try { d = await (await fetch('/taskwatch/data', { cache:'no-cache' })).json() } catch (e) { d = null }
   }
-  if (!d) { openSheet(sheetHead('任务详情') + '<div class="note">读取失败</div>'); bindSheetClose(); return }
-  if (d.error) { openSheet(sheetHead('任务详情') + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
+  if (!d) { openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取失败</div>'); bindSheetClose(); return }
+  if (d.error) { openSheet(sheetHead('任务详情') + routeNote() + '<div class="note">读取失败：' + esc(d.error) + '</div>'); bindSheetClose(); return }
   var t = d.totals || {}
-  var h = sheetHead('任务详情') + '<h3>当前会话</h3>'
+  var h = sheetHead('任务详情') + routeNote() + '<h3>当前会话</h3>'
   h += kv('会话', S.title || shortId(S.sessionId) || '未选择')
   h += kv('会话 ID', S.sessionId || '未选择')
   h += kv('工作区', S.workspace || '默认工作区')
@@ -4511,12 +4531,24 @@ if ('serviceWorker' in navigator) {
 (function () {
   try {
     var PREF_KEY = 'tw-route-pref'
+    var REMOTE_KEY = 'tw-remote-url'
     var ORIGIN = 'unknown'
     var REMOTE = ''
     var LAN = []
     var failed = false
     var upstreamOk = true
     var busy = false
+    // 2026-10-21（v1.7.1）：静态降级。宿主没有中继的 ticket / entries 接口时
+    // （拿到的就是 404 / 405），**永远不再重试**，也不弹错 —— 只是把胶囊按
+    // 「只有一个入口」隐藏，并在设置 / 详情里留一行说明与一个手动回跳链接。
+    var DEGRADED = false
+    var probeOff = false          // 宿主没有上游体检：不知道 ≠ 失败，关掉探测别每 12 秒一个 404
+    var timer = 0                  // 轮询句柄；降级 / 探测不可用时必须清掉
+    var failAt = 0                 // 换路失败后的冷却起点，防止每次轮询都重试同一次失败
+    var toastMsg = ''
+    var toastAt = 0
+    var TOAST_COOLDOWN = 30 * 1000
+    var RETRY_COOLDOWN = 30 * 1000
 
     /* ROUTE-LOGIC-BEGIN */
     function decideRoute(c) {
@@ -4536,6 +4568,102 @@ if ('serviceWorker' in navigator) {
     }
     function setPref(v) { try { localStorage.setItem(PREF_KEY, v) } catch (e) {} }
 
+    function readStore(key) { try { return localStorage.getItem(key) || '' } catch (e) { return '' } }
+    function writeStore(key, value) { try { localStorage.setItem(key, value) } catch (e) {} }
+
+    /** 上次成功切换 / 打开过的远端地址。只认 http(s)，避免 localStorage 被第三方
+     *  写进 javascript: 一类的东西后，这个链接变成一个可点的执行入口。 */
+    function rememberedRemote() {
+      var value = readStore(REMOTE_KEY)
+      return /^https?:\/\//i.test(value) ? value : ''
+    }
+    function rememberRemote(url) {
+      if (!url) return
+      var base = String(url).split('?')[0]
+      if (/^https?:\/\//i.test(base)) writeStore(REMOTE_KEY, base)
+    }
+
+    /** 其它错误的提示：同一句 30 秒内只弹一次（404/405 的降级路径不弹）。 */
+    function toast(message) {
+      if (!message) return
+      var now = Date.now()
+      if (message === toastMsg && now - toastAt < TOAST_COOLDOWN) return
+      toastMsg = message
+      toastAt = now
+      var el = document.getElementById('tw-route-toast')
+      if (!el) {
+        el = document.createElement('div')
+        el.id = 'tw-route-toast'
+        el.setAttribute('role', 'status')
+        el.setAttribute('aria-live', 'polite')
+        document.body.appendChild(el)
+      }
+      el.textContent = message
+      el.className = 'on'
+      clearTimeout(el._hide)
+      el._hide = setTimeout(function () { el.className = '' }, 3200)
+    }
+
+    function stopTimer() {
+      if (timer) { clearInterval(timer); timer = 0 }
+    }
+    function startTimer() {
+      if (timer || DEGRADED || probeOff) return
+      timer = setInterval(function () { apply(); probe() }, 12000)
+    }
+
+    /** 降级：宿主没有换路接口。清掉轮询、隐藏胶囊、不报错。 */
+    function degrade() {
+      if (DEGRADED) return
+      DEGRADED = true
+      stopTimer()
+      ORIGIN = 'unknown'
+      apply()
+    }
+
+    function isGone(status) { return status === 404 || status === 405 }
+
+    /** 兼容两种 entries 形状：中继的 {remote, lan, current} 与新契约的
+     *  {entries:[{kind, label, url, current}]}。同一份页面在中继和宿主下都能跑。 */
+    function parseEntries(j) {
+      if (!j || j.ok !== true) return false
+      var list = Array.isArray(j.entries) ? j.entries : null
+      if (list) {
+        var rem = ''
+        var lan = []
+        var current = ''
+        for (var i = 0; i < list.length; i++) {
+          var e = list[i]
+          if (!e || typeof e.url !== 'string' || !/^https?:\/\//i.test(e.url)) continue
+          if (e.kind === 'remote') { if (!rem) rem = e.url }
+          else if (e.kind === 'lan') { if (lan.indexOf(e.url) < 0) lan.push(e.url) }
+          else continue
+          if (e.current === true) current = e.kind
+        }
+        REMOTE = rem
+        LAN = lan
+        ORIGIN = current || (lan.length ? 'lan' : (rem ? 'remote' : 'unknown'))
+      } else {
+        if (j.current !== 'lan' && j.current !== 'remote') return false
+        ORIGIN = j.current
+        REMOTE = typeof j.remote === 'string' ? j.remote : ''
+        LAN = Array.isArray(j.lan) ? j.lan.slice() : []
+      }
+      if (ORIGIN === 'remote') rememberRemote(location.origin + '/taskwatch')
+      return true
+    }
+
+    /** 降级态在设置 / 详情里的一行说明。宿主页面没有中继接口这件事本身不是错误，
+     *  所以这里只陈述事实，并把「上次成功用过的远端地址」留成手动入口。 */
+    function noteHtml() {
+      if (!DEGRADED) return ''
+      var last = rememberedRemote()
+      var text = '当前页面由插件宿主提供，远端切换需要中继接口'
+      if (last) text += '；也可直接打开 <a href="' + esc(last) + '">' + esc(last) + '</a>'
+      return '<div class="note route-note">' + text + '</div>'
+    }
+    window.twRouteNote = noteHtml
+
     function mount() {
       // 2026-10-21：胶囊必须待在**标题行**里（标题与连接三点之间）。
       // 旧写法是 append 到 header 末尾、再靠 margin-left:auto 靠右，它于是成了
@@ -4580,6 +4708,7 @@ if ('serviceWorker' in navigator) {
 
     function apply() {
       var el = mount()
+      if (DEGRADED) { el.style.display = 'none'; el.setAttribute('aria-hidden', 'true'); return }
       var text = label()
       if (!text) { el.style.display = 'none'; el.setAttribute('aria-hidden', 'true'); return }
       el.textContent = text
@@ -4591,22 +4720,56 @@ if ('serviceWorker' in navigator) {
         hasLan: LAN.length > 0, hasRemote: !!REMOTE,
       })
       if (decision === 'stay' || busy) return
+      // 刚失败过就先停 30 秒：轮询每 12 秒一次，不设冷却就变成"点一次、失败、每 12 秒重试"。
+      if (Date.now() - failAt < RETRY_COOLDOWN) return
       busy = true
       fetch('/taskwatch/ticket', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ to: decision === 'toLan' ? 'lan' : 'remote' }),
-      }).then(function (r) { return r.json() }).then(function (j) {
-        if (j && j.ok && j.url) location.href = j.url
-        else busy = false
-      }).catch(function () { busy = false })
+      }).then(function (r) {
+        // 宿主没有换路接口（405）或这条路由不存在（404）：静态降级，绝不重试。
+        if (isGone(r.status)) { degrade(); return null }
+        if (!r.ok) throw new Error('HTTP ' + r.status)
+        return r.json()
+      }).then(function (j) {
+        if (j === null) { busy = false; return }
+        if (j && j.ok && j.url) {
+          if (decision === 'toRemote') rememberRemote(j.url)
+          location.href = j.url
+          return
+        }
+        busy = false
+        failAt = Date.now()
+        toast((j && j.error) || '无法切换连接方式')
+      }).catch(function (e) {
+        busy = false
+        failAt = Date.now()
+        toast('切换连接方式失败：' + ((e && e.message) || '网络错误'))
+      })
     }
 
     function probe() {
+      if (DEGRADED || probeOff) return
       fetch('/taskwatch/upstream-health', { cache: 'no-store' })
-        .then(function (r) { return r.json() })
-        .then(function (j) { failed = false; upstreamOk = !!(j && j.ok); apply() })
-        .catch(function () { failed = true; apply() })
+        .then(function (r) {
+          // 404 / 405 = 这个外壳没有上游体检（插件宿主）。拿它当"这条路断了"会误触发
+          // 一次到远端的切换，所以只关掉探测，不改失败判据。
+          if (isGone(r.status)) { probeOff = true; stopTimer(); return null }
+          if (!r.ok) throw new Error('HTTP ' + r.status)
+          return r.json()
+        })
+        .then(function (j) {
+          if (j === null) return
+          failed = false
+          upstreamOk = !!(j && j.ok)
+          apply()
+        })
+        .catch(function (e) {
+          failed = true
+          apply()
+          toast('状态检查失败：' + ((e && e.message) || '网络错误'))
+        })
     }
 
     // 样式随手挂上，不依赖页面里已有的 class（两份外壳的样式表可能不同）
@@ -4624,20 +4787,35 @@ if ('serviceWorker' in navigator) {
       + 'border:1px solid color-mix(in srgb,currentColor 24%,transparent);cursor:pointer;white-space:nowrap}'
       + '#tw-route-pill[style*="inline-flex"]{display:inline-flex!important}'
       + '#tw-route-pill:active{transform:translateY(1px)}'
+      // 换路失败的一次性提示（同一错误 30 秒内不重复弹）。同样只用 currentColor 混合，
+      // 明暗两套都能读；max-width 留出两侧 12px，390 宽下不会出现横向滚动。
+      + '#tw-route-toast{position:fixed;left:50%;bottom:calc(96px + var(--safe-b,0px));'
+      + 'transform:translateX(-50%);z-index:90;max-width:calc(100vw - 24px);box-sizing:border-box;'
+      + 'padding:10px 14px;border-radius:12px;opacity:0;pointer-events:none;transition:opacity .18s;'
+      + 'font:600 12.5px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",system-ui,sans-serif;'
+      + 'color:inherit;background:color-mix(in srgb,currentColor 12%,transparent);'
+      + 'border:1px solid color-mix(in srgb,currentColor 22%,transparent);overflow-wrap:anywhere}'
+      + '#tw-route-toast.on{opacity:1}'
+      + '@media (prefers-reduced-motion:reduce){#tw-route-toast{transition:none}}'
     document.head.appendChild(css)
 
+    // 入口清单只取一次：404/405 → 静态降级并不再重试；其它错误 → 提示一次后收手。
     fetch('/taskwatch/entries', { cache: 'no-store' })
-      .then(function (r) { return r.ok ? r.json() : null })
+      .then(function (r) {
+        if (isGone(r.status)) { degrade(); return null }
+        if (!r.ok) throw new Error('HTTP ' + r.status)
+        return r.json()
+      })
       .then(function (j) {
-        if (!j || !j.ok || (j.current !== 'lan' && j.current !== 'remote')) return
-        ORIGIN = j.current
-        REMOTE = j.remote || ''
-        LAN = j.lan || []
+        if (j === null) return
+        if (!parseEntries(j)) return
         apply()
         probe()
-        setInterval(function () { apply(); probe() }, 12000)
+        if (!probeOff) startTimer()
+      })
+      .catch(function (e) {
+        toast('入口清单读取失败：' + ((e && e.message) || '网络错误'))
       })
-      .catch(function () { /* 插件侧没有这些路由（例如从 DSH GUI 打开）→ 安静地不显示 */ })
   } catch (e) { console.warn('taskwatch: 双入口切换未启用', e) }
 })()
 </script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-in-hand",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "掌上 DSH：DeepSeek Harness 的手机端，不用装 App——会话、实时对话、交付文件、后台任务与待批准。 / DSH in hand: the phone client for DeepSeek Harness with no app to install.",
   "type": "module",
   "main": "lib/index.js",
@@ -33,7 +33,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "check": "node scripts/check-bundle.mjs && node scripts/check-files.mjs && node scripts/check-uploads.mjs && node scripts/check-queue.mjs",
+    "check": "node scripts/check-bundle.mjs && node scripts/check-files.mjs && node scripts/check-uploads.mjs && node scripts/check-queue.mjs && node scripts/check-entries.mjs",
     "demo": "node scripts/make-demo.mjs",
     "icons": "node scripts/make-icons.mjs"
   },