dsh-mobile-plugin 0.3.1 → 0.4.1

package/config/agent-presets/standard/agent.cordis.yml

@@ -166,9 +166,10 @@
   # the `user-questions/request` hook (0.2.x shape) and answers it — only the
   # tool row was missing.
   #
-  # The package must be pinned to the runtime's own generation (0.2.0-rc.2):
-  # its peerDependencies track the runtime release exactly, and the loader
-  # disables the whole row — rather than degrade — when one does not match.
+  # 这里的 `name` 是**占位**：无头宿主启动时会把同代那一份的入口绝对路径写进
+  # 一份副本（`host.js` 的 syncPresetDir），挂载的是运行时自己的那一代。这个包的
+  # peerDependencies 逐版本紧咬，对不上时 `dsh-app-boot` 会**整行禁用**（不是降级），
+  # 而钉死哪一代都不可能覆盖每台机器上装的 DSH —— 判据交给运行期，别在这里写死。
   - id: tool-ask-user
     name: '@deepseek-ai/dsh-tool-ask-user'
   # `present` 是模型**显式声明交付文件**的那一行。桌面 `standard` preset 里一直有它
@@ -180,7 +181,8 @@
   # `deliverables/presented` 事件追加进会话日志。卡片该不该出现，由**模型叫不叫这个工具**
   # 决定，不由「有没有文件被改」决定 —— 这是桌面的口径。
   #
-  # 版本必须钉在运行时那一代（当前 0.2.1-rc.2）：它的 peerDependencies 逐版本紧咬，
-  # 对不上时 `dsh-app-boot` 会**整行禁用**（不是降级），现象是模型说「没有这个工具」。
+  # 版本同样由运行期决定（见上面 tool-ask-user 那段）：0.2.1 的 `present` 要
+  # `dsh-agent` 恰好是同一代，对不上时 `dsh-app-boot` 会整行禁用，模型只会说
+  # 「没有这个工具」。`name` 是占位，宿主启动时换成本次运行时的入口。
   - id: tool-present
     name: '@deepseek-ai/dsh-tool-present'

package/dsh-mobile-credentials/lib/credentials.js

@@ -3,7 +3,7 @@
 /**
  * 每设备凭据库：签发、校验、吊销手机端的持久化凭据。
  *
- * **凭据本身就是 Bearer**（讨论记录 §3.2 的 T1 口径）。配对签发一枚
+ * **凭据本身就是 Bearer**。配对签发一枚
  * `<instanceId>.<exp>.<random>`，同一枚同时充当 `Authorization: Bearer`、`dsh_lan` cookie
  * 与 `X-Dsh-Device-Credential`。三段形状只为兼容老 App「实例号缺失时从第一段补」那条逻辑；
  * 服务端**只按整串的 sha256 查库**，不看前缀、不解析三段、也不信里面的 `exp`
@@ -13,7 +13,7 @@
  * 验签必须持有密钥本身，所以它按 base64url 原文落盘 —— 「整库只有哈希」这句话在它身上不成立。
  * `hostToken` 只为旧的 HMAC 记录保留：新记录一律留空，代理直接转发请求里出示的那一枚。
  *
- * 写入只有一个方向（§3.7）：宿主主进程是唯一写方；旁路子进程拿的是只读副本，靠文件
+ * 写入只有一个方向：宿主主进程是唯一写方；旁路子进程拿的是只读副本，靠文件
  * mtime/size 变了就重载来跟住变化，签发与吊销走 IPC 交给主进程（`lib/impl.js`）。
  */
 const crypto = require('node:crypto');
@@ -24,7 +24,7 @@ const os = require('node:os');
 const FILE = process.env.DEVICE_CREDENTIALS_FILE || path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'relay-device-credentials.json');
 /** 默认有效期一年。`issue(..., ttlMs)` 可覆盖；`ttlMs <= 0` 表示不过期。 */
 const DEFAULT_TTL_MS = 365 * 24 * 3600 * 1000;
-/** 已吊销或过期超过这么久的记录，下次写入时整条删掉（§3.9）：别让每条请求扫一整年的账。 */
+/** 已吊销或过期超过这么久的记录，下次写入时整条删掉：别让每条请求扫一整年的账。 */
 const PRUNE_GRACE_MS = 30 * 24 * 3600 * 1000;
 /** 剩余有效期超过这个比例就不续期：滑动续期只在过掉一半之后发生。 */
 const RENEW_BELOW_RATIO = 0.5;
@@ -142,7 +142,7 @@ function deviceMeta(device) {
 }
 
 /**
- * 已吊销、或过期超过宽限期的整条删掉（§3.9）。
+ * 已吊销、或过期超过宽限期的整条删掉。
  *
  * 旧库只追加、吊销只打标记，今天不疼是因为「查不到就回退验 HMAC」把问题掩盖成了可用；
  * 查库优先之后，每条请求都要扫整张表，一年下来几千条就是每条请求扫几千次。
@@ -257,7 +257,7 @@ function findByKeyId(instanceId, keyId) {
 }
 
 /**
- * 记一次「这台设备刚连上过」（§3.4）。
+ * 记一次「这台设备刚连上过」。
  *
  * 内存里每次都更新（面板 3 秒轮询要的是当下的值），落盘按全局 1 分钟节流：每条请求都写一次
  * 盘，是拿磁盘换一个只用来显示「几分钟前」的字段。`issue` / `revoke` 立刻写，不受它影响。
@@ -269,7 +269,7 @@ function touch(record, info = {}) {
   record.lastSeenAt = now;
   const channel = typeof info.channel === 'string' ? info.channel : '';
   if (channel) record.lastChannel = channel.slice(0, FIELD_MAX);
-  // 身份那几格（2026-10-26）：名字 / 平台 / 系统版本 / App 版本由**每一次请求**带上来，
+  // 身份那几格：名字 / 平台 / 系统版本 / App 版本由**每一次请求**带上来，
   // 顺手刷新。它们以前只在配对那一刻写一次，于是「手机升到新版了、面板还报配对时的旧版本」，
   // 而旧会话升级写进来的记录干脆什么身份都没有（面板只能画「未知设备」）。
   // **只写这次真带了值的格子**：老版本 App 不带头，绝不能把已经有的名字冲成空。
@@ -290,7 +290,7 @@ function touch(record, info = {}) {
 }
 
 /**
- * 滑动续期（§3.9）：剩余不到一半就把 `expiresAt` 后推一个新 TTL。
+ * 滑动续期：剩余不到一半就把 `expiresAt` 后推一个新 TTL。
  *
  * 不需要新协议 —— 服务端本来就以记录为准、不验 token 里的 `exp`，所以续期就是改这条记录。
  * **不能改 token 本身**：库按整串哈希查，改一个字节手机上那枚就对不上了。
@@ -362,7 +362,7 @@ function listActive() {
 }
 
 /**
- * 面板要的那份设备清单（§3.4）。
+ * 面板要的那份设备清单。
  *
  * 按 `deviceId` 聚成一行：同一台手机重配几次不该在列表里重复出现。名字与平台取最新一条
  * **有值的**记录（老记录这些字段是空的，空的不能覆盖有值的），绑定时间取最早，最近连接取

package/host.js

@@ -2,33 +2,35 @@
 /**
  * Headless Cordis Host for the DSH mobile app.
  *
- * The repository used to ship an Electron desktop shell that owned the Host
- * process; the DSH mobile app never used that surface. This entry replaces it:
- * it boots the same upstream Cordis Host, composes the shipped DSH Web
- * bundle, and adds one plugin — the mobile API at `/api/mobile/v1`.
+ * Boots the upstream Cordis Host, composes the shipped DSH Web bundle, and adds
+ * one plugin — the mobile API at `/api/mobile/v1`.
  *
- * The Host itself is upstream. `@deepseek-ai/dsh-app-boot#boot` mounts a
- * `cordis.yml` entry list, so the root list stays empty and every plugin is
- * contributed by a patch layer: the profile's bundle layers (dsh-base then
- * dsh-web-app), the profile's own `cordis.patch.yml`, and finally this
- * package's `cordis.patch.yml`.
+ * `@deepseek-ai/dsh-app-boot#boot` mounts a `cordis.yml` entry list, so the root
+ * list stays empty and every plugin comes from a patch layer: the profile's
+ * bundle layers (dsh-base then dsh-web-app), the profile's own
+ * `cordis.patch.yml`, and finally this package's `cordis.patch.yml`.
  */
 
-import { existsSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
 import { installProcessGuard } from './lib/host-guard.cjs'
+import { DIRECTORY_PICKER_ROW, TOOL_ROWS, pinInsertedRows, syncPresetDir } from './lib/host-compat.cjs'
 import { dropBareNameSelfMounts } from './lib/host-patches.cjs'
 import {
   assertEntriesActivated,
   boot,
+  evaluatePluginCompatibility,
+  getDshRuntimeVersion,
   initProfile,
   installFailLoud,
   loadLayeredEnv,
   loadOverlayPatches,
   loadProfile,
   PROFILE_TEMPLATES,
+  readProfileCompatibility,
   resolveProfileDir,
 } from '@deepseek-ai/dsh-app-boot'
 
@@ -62,24 +64,19 @@ try {
   /**
    * 本插件是**装在这个 profile 里**的，还是「源码树直接跑」的？
    *
-   * 这两种现场的挂载方式不一样，而差别全在「挂哪一份入口」上（2026-10-11 起两条都留着）：
+   * 两种现场挂的不是同一份入口：
+   *  - **装在 profile 里**（桌面端）→ 挂 `<profile>/node_modules/dsh-mobile-plugin/lib/index.js`，
+   *    即**稳定外壳**：查更新、装新版、就地换代都在它手里，面板上才有「检查 / 立即更新」。
+   *  - **源码树直接跑**（无头部署、开发时 `node host.js`）→ 没有任何人把它放进 `node_modules`，
+   *    于是挂随包发布的 `lib/impl.js`。代价是**没有外壳**，那台只能同步源码 + 重启宿主。
    *
-   *  - **装在 profile 里**（桌面端；服务器那台改成 `pnpm 装进 profile` 之后也是）→ 挂
-   *    `<profile>/node_modules/dsh-mobile-plugin/lib/index.js`，也就是**稳定外壳**：
-   *    查更新、装新版、就地换代那一套全在它手里，所以面板上才有「检查 / 立即更新」。
-   *  - **源码树直接跑**（老的无头部署、开发时直接 `node host.js`）→ 插件**就是** Loader 自己
-   *    正跑的那个包，没有任何人把它放进 `node_modules`，于是这一支挂随包发布的
-   *    `lib/impl.js`（真正的实现）。代价是**没有外壳** → 那台的面板里更新不了，只能同步
-   *    源码 + 重启宿主。
+   * **两处都走绝对路径而不是包名**：`cordis.patch.yml` 里那行按包名挂载是给桌面端用的，
+   * 无头宿主这边解析不到 —— loader 从**它自己所在的位置**解析包名，而它在宿主自己的依赖树里，
+   * 看不见 profile 里装的那份。loader 对解析失败不是留一条警告，是**整棵插件树加载失败**，
+   * 所以那行在这里一律摘掉，由这里按绝对路径插一行。装没装 profile 决定的是**挂哪一份**，
+   * 不是挂不挂。
    *
-   * **两处都走「绝对路径」而不是包名**：`cordis.patch.yml` 里那行按包名挂载是给桌面端用的，
-   * 无头宿主这边解析不到 —— loader 是从**它自己所在的位置**解析包名的（实测报错原文：
-   * `Cannot find package 'dsh-mobile-plugin' imported from <…>/@deepseek-ai/cordis-plugin-loader/lib/index.js`），
-   * 而它在宿主自己的依赖树里，profile 里装的那份它根本看不见。而 loader 对解析失败不是留一条
-   * 警告，是**整棵插件树加载失败**（服务器那台当年就是这么完全起不来的）。所以那行在无头宿主
-   * 里一律摘掉，由这里按绝对路径插一行 —— 装没装 profile 决定的是**挂哪一份**，不是挂不挂。
-   *
-   * 判据取「profile 里有没有这个包」，不看环境变量、不看目录名：装没装是事实，改不了口径。
+   * 判据取「profile 里有没有这个包」，不看环境变量、不看目录名：装没装是事实。
    */
   const installedDir = join(profileDir, 'node_modules', BIN_NAME)
   const selfInstalled = existsSync(join(installedDir, 'package.json'))
@@ -90,6 +87,82 @@ try {
   const rootConfig = join(profileDir, 'cordis.root.yml')
   writeFileSync(rootConfig, '[]\n')
 
+  /**
+   * 官方工具行跟着**运行时**换代，本包不再自带一份钉死的副本。
+   *
+   * 这三个包（提问工具 / 交付文件工具 / 目录浏览后端）互相之间用精确版本咬死，
+   * 而装载前的预检对不上的处理不是降级、是**整行禁用** —— 现象是手机上
+   * 「模型说没有这个工具」「添加工作区列不出目录」，桌面上却一切正常。钉在哪一代
+   * 都不对：官方每抬一次代，钉死的副本就失效一次，而一台机器上装的 DSH 是哪一代
+   * 我们发版时并不知道。
+   *
+   * 判据直接用 `dsh-app-boot` 自己导出的 `evaluatePluginCompatibility`，与装载前那次
+   * 预检**同源**：自己写一套 semver 只会让两边分叉，这里放过的行照样被预检禁掉。
+   * 先问运行时那棵树，再问本包自带的那份，都不行就返回 null —— 那一行保持原样，
+   * 交给官方预检去禁用并打印原因，等于退回旧行为，不会更差。
+   */
+  let runtimeRequire = null
+  try {
+    runtimeRequire = createRequire(new URL(import.meta.resolve('@deepseek-ai/dsh-app-boot')))
+  } catch (error) {
+    // 定位不到不是致命：下面每一行都会退回本包自带的那份，最差回归旧行为。
+    process.stderr.write(`${BIN_NAME}: 定位不到运行时那棵依赖树（${error?.message || error}），这一轮只按本包自带的解析\n`)
+  }
+  const bundledRequire = createRequire(import.meta.url)
+  const runtimeVersion = getDshRuntimeVersion()
+  let exemptions = {}
+  try {
+    exemptions = readProfileCompatibility(profileDir).exemptions
+  } catch (error) {
+    process.stderr.write(`${BIN_NAME}: 读不了 profile 的兼容性豁免文件，这一轮按无豁免处理：${error?.message || error}\n`)
+  }
+
+  const resolveGeneration = (scope, require, name) => {
+    if (!require) return null
+    try {
+      const manifestPath = require.resolve(`${name}/package.json`)
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      const issue = evaluatePluginCompatibility(manifest, exemptions, runtimeVersion)
+      if (issue !== undefined && !issue.exempted) return null
+      return { scope, name, version: manifest.version, entry: require.resolve(name) }
+    } catch {
+      return null
+    }
+  }
+
+  const pinnedRows = new Map()
+  for (const { id, name } of [...TOOL_ROWS, DIRECTORY_PICKER_ROW]) {
+    const hit = resolveGeneration('运行时', runtimeRequire, name)
+      ?? resolveGeneration('本包自带', bundledRequire, name)
+    if (hit) pinnedRows.set(id, hit)
+    process.stderr.write(
+      hit
+        ? `${BIN_NAME}: ${name} → 用${hit.scope}的 ${hit.version}\n`
+        : `${BIN_NAME}: ${name} 没解析到与 dsh ${runtimeVersion} 同代的一份，这一行维持原样（装载预检会说明它为什么被禁用）\n`,
+    )
+  }
+
+  // 预设里的两行默认按裸名写：Loader 从它自己的位置解析，命中哪一份不由我们决定。
+  // 解析到了同代的那份就改写一份副本给它，路径写死成那一份的入口。
+  const presetRoots = {}
+  for (const { id } of TOOL_ROWS) {
+    const hit = pinnedRows.get(id)
+    if (hit) presetRoots[id] = hit.entry
+  }
+  const presetDir = TOOL_ROWS.some(({ id }) => presetRoots[id] !== undefined)
+    ? syncPresetDir(
+      join(PACKAGE_DIR, 'config', 'agent-presets'),
+      join(profileDir, '.mobile-agent-presets'),
+      presetRoots,
+    )
+    : join(PACKAGE_DIR, 'config', 'agent-presets')
+
+  // patch 层里的 insert 行按包名写（`cordis.mobile-host.yml` 的目录浏览器），
+  // 同样换成解析到的那份入口。只改 insert：patch 里其它形态的 name 是断言，
+  // 改它会让整条 patch 被静默跳过。
+  const entryByName = {}
+  for (const hit of pinnedRows.values()) entryByName[hit.name] = hit.entry
+
   const patches = [
     ...profile.layers.flatMap(layer => layer.patches),
     ...profile.patches,
@@ -123,16 +196,18 @@ try {
       id: 'agent-presets',
       config: {
         default: 'standard',
-        roots: [{ path: join(PACKAGE_DIR, 'config', 'agent-presets'), trust: 'system' }],
+        roots: [{ path: presetDir, trust: 'system' }],
       },
     },
   ]
 
+  const pinnedPatches = pinInsertedRows(patches, entryByName)
+
   process.stderr.write(
     `${BIN_NAME}: 挂载方式 = ${selfInstalled ? `profile 里装的那份（${installedDir}，带稳定外壳，面板里能自更新）` : '源码树直挂（无外壳，更新靠同步源码 + 重启宿主）'}\n`,
   )
 
-  const ctx = await boot(BIN_NAME, rootConfig, patches, (hostCtx) => {
+  const ctx = await boot(BIN_NAME, rootConfig, pinnedPatches, (hostCtx) => {
     // A headless mobile host has no command line: nothing passes flags and
     // nobody is watching a help screen. The web startup plugin still waits on
     // `cmdlineArgs` before it will provide `webStartup`, so the service must
@@ -147,17 +222,11 @@ try {
   await assertEntriesActivated(ctx, BIN_NAME)
   // 装载期结束，撤掉 installFailLoud 的兜底。
   //
-  // 它自己的语义是对的：一个插件**装载**失败不该让宿主半死不活地上线，所以
-  // 任何 unhandledRejection 都直接 exit(1)。但它注册在 process 上之后**一辈子
-  // 不摘**（releaseFailLoud 在成功路径上从来没被调用过），而宿主是长驻进程——
-  // 于是运行期任意一次游离 reject 都会走到它那里把进程带走。上一版提交
-  // （ca60417）在真机上被这条打脸：账本记下了「未处理的 Promise 拒绝（已忽略）」，
-  // 紧接着一行 `fatal load failure` 就把 PID 换掉了。
-  //
-  // 这里在 assertEntriesActivated 通过之后才撤：那一刻树已经确认全部激活
-  //（激活失败的 entry 会在它内部 throw，进上面的 catch 走 boot failed），
-  // 此后再出现的 reject 就不再是「装载失败」而是运行期故障，
-  // 交给进程级错误边界记账 + 熔断。
+  // 它注册在 process 上之后**一辈子不摘**，而宿主是长驻进程 —— 运行期任意一次游离
+  // reject 都会走到它那里把进程带走，而它本该只管「装载失败」。所以这里在
+  // assertEntriesActivated 通过之后才撤：那一刻树已确认全部激活（激活失败的 entry 会在
+  // 它内部 throw，进上面的 catch 走 boot failed），此后的 reject 是运行期故障，交给
+  // 进程级错误边界记账 + 熔断。
   releaseFailLoud()
   process.stderr.write(`${BIN_NAME}: mobile host ready (profile ${PROFILE_NAME})\n`)
 } catch (error) {

package/lib/client.js

@@ -1,40 +1,12 @@
 /**
  * dsh-mobile-plugin 的**客户端半边**（在 DSH 桌面 Web 页面里运行）。
  *
- * 它做四件事：
+ * 四件事：桌面侧边栏的展开态与「读过了」报给宿主；手机端的已读回执应用回桌面绿点；
+ * 提供「设置 → 移动端」那颗由本机打开的网页管理开关。方向是单向的（桌面 → 宿主 → 手机），
+ * 手机上的折叠只存在 App 本地，不写回。
  *
- * 1. **桌面端工作区展开态 → 宿主**。桌面侧边栏「哪些工作区分组是展开的」只记在
- *    **浏览器 localStorage**（`dsh.workspace.view.vN`，由 @deepseek-ai/dsh-client-ui-workspace
- *    的 createWorkspaceViewStore 持久化到 dsh-client-store 的 localStorage），
- *    宿主进程、中转和手机都读不到。移动端要与桌面端对齐展开态，就只能由页面里的
- *    这一半把状态读出来交给宿主。
- *
- *    数据方向是单向的：桌面 → 宿主 → 手机。手机上手动折叠/展开只存在 App 本地
- *    （AsyncStorage），不会写回这份 localStorage。
- *
- * 2. **设置 →「移动端」**（设置菜单里的顶层一项，不再挂在内置插件页签下）。保留
- *    **网页版入口**，并只加一颗由可信本机 DSH 设置页操作的公网访问开关；网页管理默认关闭，
- *    每次开启固定 2 小时，到期不因访问续时。管理界面本体仍在宿主吐出的 HTML 里。
- *
- *    为什么这里只加开关：这半边不可热替换，管理界面继续留在网页版；本机开关只控制
- *    网页管理路由，不改手机 App API 或隧道状态。插件更新仍交给 DSH 插件市场。
- *
- * 3. **桌面端已读 → 宿主**（`startDesktopReadSync`）。桌面侧栏的「已完成待读」绿点
- *    只活在渲染进程内存里（`UiSession.completionUnread`），宿主和手机都读不到。
- *    这一半盯着 `uiSession.sessionStatus`，把「刚从未读集合掉出去」的会话报给
- *    `/api/relay/desktop-read`，宿主据此清掉手机端那份完成提醒。
- *
- * 4. **手机端已读 → 桌面端**（`startReadReceiptSync`）。反方向：宿主把手机端读过
- *    哪些会话记成 `sessionId → readAt` 台账，这一半拉下来，对水位前进过的会话做一次
- *    瞬时 `sessions.retain(id, { source: 'mainView' })` + `release()`，借桌面自己的
- *    `reconcileStatus()` 把绿点摘掉。见 lib/read-receipt.cjs 的文件头。
- *
- * 写成惰性工厂（`window.__ModuleLoader__.load`）是 DSH 客户端插件的约定：
- * 运行 bundle 只注册工厂，副作用（这里的定时器、页签注册）在物化时才发生。
- * 工厂收到的 `require` 是 DSH 的模块表 require，`react` 是平台 seed word。
- *
- * 本文件**不经任何构建**（package.json 的 files 直接收录 lib 下的 .js），所以不能
- * 写 JSX：统一用 `React.createElement` 的别名 `h`。
+ * 本文件不经任何构建（package.json 直接收录 lib 下的 .js），所以不能写 JSX，统一用
+ * `React.createElement` 的别名 `h`；客户端插件按约定写成惰性工厂，定时器与页签在物化时才起。
  */
 
 window.__ModuleLoader__.load({
@@ -195,18 +167,11 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * 控制面调用。`path` 既可以是 `/xxx` / `xxx` 这样的**短路径**（推荐，与
-     * `postJson('/desktop-read')` 的写法一致），也可以直接甩一个完整的
-     * `/api/relay/xxx` 或 `api/relay/xxx`——几种都接受，最终一律折成文档相对地址。
+     * 控制面调用。`path` 既接受 `/xxx` 这样的短路径，也接受已经带 `/api/relay` 的全路径，
+     * 几种都折成文档相对地址。
      *
-     * **为什么必须几种都接受（2026-10-10 真机故障）**：这里以前是无条件
-     * `${RELAY}${path}`，而绿点那两条同步传进来的偏偏是**已经带 `/api/relay` 的全路径**
-     * （`READ_RECEIPT_ENDPOINT` / `DESKTOP_READ_ENDPOINT`），于是真正发出去的是
-     * `/api/relay/api/relay/read-receipt` —— 一个不存在的地址。它返回 401/404，被
-     * 两条同步各自的 `catch` 静静吞掉，所以「手机上读过桌面不灭灯」「桌面上读过手机
-     * 不灭灯」从来就没通过，而且**一条日志都不留**（宿主侧活体台账里那两个计数恒为 0）。
-     * 改断言而不是改实现是不行的：守卫测试里的假 fetch 按 `endsWith(endpoint)` 匹配，
-     * 而 `/api/relay/api/relay/read-receipt` 也满足这个后缀 —— 测试因此一直是绿的。
+     * 必须两种都认：绿点那两条同步传进来的本来就是全路径，无条件拼前缀会发到
+     * `/api/relay/api/relay/...` 这个不存在的地址，而调用方的 catch 会把它静静吞掉。
      */
     function controlUrl(path) {
       const raw = String(path);
@@ -241,15 +206,14 @@ window.__ModuleLoader__.load({
     });
 
     /* ── 三：侧边栏未读绿点的双向同步 ───────────────────────────────────────
-     * 两端的绿点是**两份互不相干**的状态：
+     * 两端的绿点是两份互不相干的状态：
      *   - 手机端 = 宿主按设备维度维护的完成提醒（lib/mobile/completion.js），
      *     由 `POST /api/mobile/v1/session/read` 清掉；
      *   - 桌面端 = 渲染进程内存里的 `UiSession.completionUnread`，既不落盘也不过服务端。
-     * 所以「手机上读过了，桌面还亮着」和「桌面上读过了，手机还亮着」都得靠这一半补。
+     * 两边各缺一块，所以两个方向都要这一半补。
      *
-     * 这两条同步都要桌面端的服务（uiSession / sessions），拿不到就整条不启动：
-     * 注册了也只是空转的定时器。`ctx.get` 在 Cordis 上恒有，服务可能比我们晚就位，
-     * 所以每个 tick 现取一次，而不是启动时取一次。
+     * 两条同步都依赖桌面端的服务（uiSession / sessions），拿不到就整条不启动：注册了
+     * 也只是空转的定时器。服务可能比我们晚就位，所以每个 tick 现取一次。
      */
     /** 轮询间隔：与展开态同步同频。绿点晚 2s 灭掉无感，但没必要更勤。 */
     const READ_SYNC_INTERVAL_MS = 2000;
@@ -286,15 +250,11 @@ window.__ModuleLoader__.load({
     /**
      * 方向一：桌面端读过了 → 告诉宿主，手机端侧栏灭灯。
      *
-     * 三种情形算「桌面读过了」，每种只报一次（变回未读或重新跑起来时摘掉标记、可以再报）：
-     *   - 本次打开页面之后**看见它从别的状态变成未读、又掉出去**（普通的点开）；
-     *   - 此刻**正开在主视图里**（`retainedBy.mainView > 0`：用户盯着它读完，它压根不进未读集合）；
-     *   - 本次打开页面之后**它变过、而且现在不是未读**（补掉漏采的那一瞬间）。
+     * 三种情形算「桌面读过了」，每种只报一次：看见它从未读里掉出去、此刻正开在主视图里
+     * （`retainedBy.mainView > 0`）、或本次页面里它变过且现在不是未读。
      *
-     * **首帧一条都不报**：桌面页面刚加载时 `sessionStatus` 里全是 `completionUnread: false`
-     * （`completionUnread` 只在浏览器内存里，重开页面就没了），照单全收会把手机上真的
-     * 未读全灭掉。所以「页面打开之后变过」这条要求 `updatedAt > 页面打开时刻`，
-     * 没拿到会话清单时宁可不报。
+     * 首帧一条都不报：页面刚加载时 `sessionStatus` 里全是 `completionUnread: false`，
+     * 照单全收会把手机上真未读的全灭掉。所以要求 `updatedAt > 页面打开时刻`。
      */
     function startDesktopReadSync(ctx) {
       withClientServices(ctx, ['uiSession'], 'uiSession', 'mobile-plugin: 桌面端已读上报', (scope, isDisposed) => {
@@ -381,15 +341,9 @@ window.__ModuleLoader__.load({
      * 拿到桌面客户端的两个服务：`uiSession`（未读绿点的真源 + 每会话运行态）与
      * `sessions`（会话清单 + `retain`）。
      *
-     * **必须用 `ctx.inject([...], child => …)`，不能用 `ctx.get(name)`。** 2026-10-10
-     * 真机故障：两条绿点同步通道一条都没在跑 —— 宿主侧的活体台账（`/api/relay/status`
-     * 的 `desktopHalf`）显示桌面半边**一次 read-receipt 都没拉过**，而 read-receipt 那条
-     * effect 是**无条件 2s 轮询**、`ctx.get` 之后才 fetch，所以只可能是 tick 在服务这一
-     * 道 guard 上就返回了。同一个桌面里能正常工作的客户端插件（内置的 conversation /
-     * approval、第三方 `dsh-opencode-go`）一律走 `inject`：DSH 自己的插件把服务写进
-     * `inject` 数组，opencode-go 用 `ctx.inject([...], child => …)`。`ctx.get` 是「绕过
-     * 注入直接取」，在客户端运行时里取不到这两个服务。拿不到就一个定时器都不起（与旧
-     * 行为一致），由 lib/client.js 的自检上报把「到底看见了什么」说给宿主听。
+     * 必须用 `ctx.inject([...], child => …)`，不能用 `ctx.get(name)`：`ctx.get` 是绕过注入
+     * 直接取，在客户端运行时里取不到这两个服务，两条绿点同步会一条都不跑。拿不到就一个
+     * 定时器都不起，由自检上报把「到底看见了什么」说给宿主听。
      */
     /**
      * 客户端半边的自检状态：只给自检上报用（谁注入了、谁没注入）。
@@ -437,16 +391,12 @@ window.__ModuleLoader__.load({
      * 方向二：手机上读过了 → 在桌面页面里就地清掉绿点。
      *
      * 拉宿主那份 `sessionId → readAt` 台账，对水位前进过的会话做一次瞬时
-     * `sessions.retain(id, { source: 'mainView' })` + 同 tick `release()`。桌面自己的
-     * `reconcileStatus()` 订阅了列表 store，而 `retain` 里的 `publishRetention` 会同步
-     * 抬 `retainedBy.mainView`，于是 `completionUnread.delete(id)` 在 release 之前就已经
-     * 发生；release 把引用数降回 0 也不会把绿点加回来（只有 `observeRunning(false)`
-     * 且非 mainView 才会加）。整个过程同一个 tick 内完成，React 还没重渲染，看不到抖动。
+     * `sessions.retain(id, { source: 'mainView' })` + 同 tick `release()`：`retain` 会同步
+     * 抬 `retainedBy.mainView`，桌面自己的 `reconcileStatus()` 因此摘掉绿点，而 release
+     * 把引用数降回 0 也不会把它加回来。同一个 tick 内完成，React 还没重渲染，看不到抖动。
      *
-     * 为什么还要跟 `updatedAt` 比一次：台账只记「读过」不记「读完之后又跑完了一轮」。
-     * 若不管这一条，桌面端**重新打开页面**时（内存里的 applied 游标是空的）会把一条
-     * 早已被新一轮完成盖过的旧回执重新应用，把本该亮的绿点灭掉。会话的最后活动时间
-     * 晚于已读水位，就说明这一轮是读完之后才跑完的，必须跳过。
+     * 还要跟 `updatedAt` 比一次：台账不记「读完之后又跑完了一轮」，重新打开页面时会把
+     * 旧回执重新应用，灭掉本该亮的绿点。最后活动时间晚于已读水位就跳过。
      */
     function startReadReceiptSync(ctx) {
       withClientServices(ctx, ['sessions'], 'sessions', 'mobile-plugin: 已读回执应用', (scope, isDisposed) => {
@@ -682,14 +632,11 @@ window.__ModuleLoader__.load({
     /**
      * 客户端半边的自检上报：每 10s 把「这一半到底看见了什么」报给宿主。
      *
-     * 为什么要它：宿主能数出「那半边没来敲门」（`/api/relay/status` 的 `desktopHalf`），
-     * 但数不出「它为什么没来」。2026-10-10 那次故障里，正是这一点让「服务没拿到」和
-     * 「服务拿到了但清理失败」两种可能耗掉了一整轮排查 —— 这条通路把答案直接摆出来：
-     * 两条同步各自的 `ctx.inject` 到底有没有回调（`uiSession` / `sessions` 两格）、
-     * `ctx.get` 能不能看见那两个服务、最后一次错在哪。
+     * 宿主能数出「那半边没来敲门」，数不出「为什么没来」。这条通路直接摆出：两条同步各自的
+     * `ctx.inject` 有没有回调、`ctx.get` 能不能看见那两个服务、最后一次错在哪。
      *
-     * 刻意**不**依赖任何客户端服务：探测全包在 try/catch 里，它自己要是也挂在服务上，
-     * 就永远报不出「服务拿不到」这件事了。
+     * 刻意不依赖任何客户端服务：探测全包在 try/catch 里，它自己挂在服务上就永远报不出
+     * 「服务拿不到」这件事。
      */
     function startClientHalfReport(ctx) {
       const probe = (name) => {

package/lib/desktop-view.cjs

@@ -3,17 +3,12 @@
 /**
  * 桌面端工作区视图快照（侧边栏展开/折叠）的宿主侧存储。
  *
- * 桌面端把「哪些工作区分组是展开的」只记在**浏览器 localStorage**
- * （`dsh.workspace.view.v5`，见 @deepseek-ai/dsh-client-ui-workspace 的
- * createWorkspaceViewStore → dsh-client-store 的 localStorage 持久化），
- * 宿主进程、中转和手机都读不到它。插件因此带了一个客户端半边（lib/client.js）：
- * 桌面页面里每 2 秒读一次这份状态，变了就 POST `/api/relay/desktop-view`，
- * 由本模块落到 `$DSH_HOME/desktop-view.json`，再由 `/api/mobile/v1/desktop-view`
- * 下发给 App。
+ * 桌面端只把展开态记在浏览器 localStorage 里，宿主、中转和手机都读不到；插件因此带了
+ * 客户端半边（lib/client.js）：桌面页面定期读出来 POST `/api/relay/desktop-view`，由本模块
+ * 落到 `$DSH_HOME/desktop-view.json`，再由 `/api/mobile/v1/desktop-view` 下发给 App。
  *
- * 语义与桌面端严格一致：`groupExpansion` 以 **workspaceId** 为键（未分组分组固定为
- * 空串 `''`），只有**显式 true** 表示展开，缺省＝折叠；桌面端在「当前会话所属分组
- * 还没有记录」时会自动展开它并落盘，所以「当前会话所在工作区」通常也在里面。
+ * 语义与桌面端一致：`groupExpansion` 以 workspaceId 为键（未分组固定为空串），只有显式
+ * true 表示展开，缺省即折叠；当前会话所属分组桌面端会自动展开，所以通常也在里面。
  */
 
 const fs = require('node:fs');

package/lib/git/read.js

@@ -383,12 +383,11 @@ function githubTargetOf(remote) {
 /**
  * GitHub 元信息（星标 / Fork / 关注）。
  *
- * 只取这三个数字，**不取星标曲线**：曲线要把 stargazers 一页页翻完（100 条一页），几千星的
- * 仓库等于几十次请求，撞上匿名限流就是整页变慢；数字本身一次请求就够。
+ * 只取这三个数字，不取星标曲线：曲线要把 stargazers 一页页翻完，几千星的仓库等于几十次
+ * 请求，撞上匿名限流就整页变慢。有 `GITHUB_TOKEN` / `GH_TOKEN` 时带上，私有仓库也能读。
  *
- * 「读不到」要和「没有 GitHub 远端」分开说：私有仓库的匿名请求回 404，跟「这个项目根本没关联
- * GitHub」是两件事，前端那句话必须说对。有 `GITHUB_TOKEN` / `GH_TOKEN` 环境变量时带上它 ——
- * 私有仓库靠这一个头就能读，不必在 App 里输任何东西。
+ * 「读不到」和「没有 GitHub 远端」要分开：私有仓库的匿名请求回 404，是两件事，前端那句
+ * 话必须说对。
  */
 async function githubOf(root) {
   const remotes = await remotesOf(root);
@@ -564,9 +563,8 @@ async function activityOf(root) {
 /**
  * 仓库概览：远端、语言占比、代码量、近 12 周活动，外加（能取到时）GitHub 的三个数字。
  *
- * 这张卡最贵（这台仓库实测扫一遍约 3 秒），所以：① 结果按仓库缓存一分钟，`fresh` 跳过；
- * ② 每项都自己兜底 —— 语言统计读文件有上限，历史统计失败就退化成 0，GitHub 取不到就整块
- * 不给。它不该把整页拖垮。
+ * 这张卡最贵，所以结果按仓库缓存一分钟（`fresh` 跳过），每项都自己兜底：语言统计有读取
+ * 上限，历史统计失败退化成 0，GitHub 取不到就整块不给。它不该把整页拖垮。
  */
 async function overviewOf(root, options = {}) {
   const cached = overviewCache.get(root);