dsh-mini-remote 0.1.8 → 0.1.9

package/lib/index.js

@@ -30,6 +30,19 @@ import z from '@deepseek-ai/schemastery'
 import { createStore } from './store.js'
 import { createTurnTracker, visibleText, stepSelfTalk } from './events.js'
 import { replayHistory, lastReply } from './history.js'
+import { createTrajectoryTracker, replayTrajectory, capTrajectory } from './trajectory.js'
+
+/**
+ * Agent 模式（内置四档）的中文词条。**照抄 PC 的词条表**（dsh-client-ui-agent-preset
+ * 里的 presetStandardName / presetStandardDescription 等八个键），一个字不改。
+ * 自建模式不进这张表——PC 的政策原话是「不翻译用户自造的名字」。
+ */
+const AGENT_MODE_COPY = {
+  standard: ['标准模式', '处理代码、文件和资料，适合大多数任务。Agent 会按需使用检索、编辑和终端等工具。'],
+  ptc: ['PTC 模式', '包含标准模式的所有能力，更适合批量调用工具，并对结果进行筛选、整理、去重、统计或汇总的任务。'],
+  minimal: ['极简模式', 'Agent 仅使用终端工具完成任务，适合测试和对比其基础表现。'],
+  cordis: ['创造模式', '用对话定制 DSH：让 Agent 编写插件，添加新功能或界面；也能组合工具和提示词，创建自己的模式。'],
+}
 import { readTailEvents, findSessionLog } from './log-tail.js'
 import {
   parseSlashLine, describeCommands, commandRow, commandPatch,
@@ -45,6 +58,8 @@ import { ensureCloudflared } from './cloudflared.js'
 import { startTunnel, TUNNEL_HINT } from './tunnel.js'
 import { listWorkspaces, listSessionsOf, createSessionIn, createWorkspaceAt } from './tree.js'
 import { createTitleCache } from './title-cache.js'
+import { createSessionMetaCache } from './session-meta-cache.js'
+import { createSubagentCache } from './subagent-cache.js'
 import { listRoots, listDirectory, makeDirectory } from './browse.js'
 import { listPresets, setPreset, available as presetsAvailable } from './permissions.js'
 import { buildId } from './build.js'
@@ -334,7 +349,18 @@ export function apply(ctx, config = {}) {
    * 而这件事**每重启一次就得重付一遍**——标题却是定下来基本不变的东西。
    */
   const titles = createTitleCache({ file: join(dir, 'titles.json') })
+  const sessionMeta = createSessionMetaCache({ file: join(dir, 'session-meta.json') })
+  const subagentCache = createSubagentCache({ file: join(dir, 'subagents.json') })
   const tracker = createTurnTracker()
+  /**
+   * 执行轨迹的累计器（「完整」模式要的过程区）。
+   *
+   * **和上面的 tracker 是两个人**：上面那个只认「用户说的话」和「最终回答」，轨迹那个
+   * 认的是思考、工具调用、工具结果。分开的理由是它们服务的是**两种模式**——聊天模式的
+   * 回答区里一个字的过程都不该有（2026-09-22 用户亲自否掉的），而完整模式要的就是过程。
+   * 两条路共用的是同一批原始事件，不是同一份产出。
+   */
+  const trajectory = createTrajectoryTracker()
   // 队列的真相在 agent 的收件箱里，store 拿不到 ctx，所以给它一个回调去问。
   // 不缓存、每次取快照现读：没有第二份状态，也就不会和电脑上不一致。
   store.setQueueSource(queuedOf)
@@ -1185,11 +1211,100 @@ export function apply(ctx, config = {}) {
     return win
   }
 
+  /**
+   * 喂一口执行轨迹，并把这一批的变化推给**正在看这个会话、而且要「完整」模式**的手机。
+   *
+   * 三个决定，都有理由：
+   *   ① **落在 store 的内存缓冲里**，不落盘（体积是回答正文的 90.7 倍，落盘那份是每
+   *      500 毫秒重写整份 JSON；理由见 lib/store.js 的 trajectoryBySession）。
+   *   ② **只推当前绑定的那个会话**（和 reply 那条同一个口径）：手机遥控的是这一个，
+   *      别的会话在想什么跟它无关；那些会话照旧攒在缓冲里，切过去时用接口拉一份。
+   *   ③ **推的是增量帧**，不是整份快照（见 lib/server.js 的 broadcastTrajectory）。
+   */
+  function feedTrajectory(sessionId, event) {
+    const change = trajectory.feed(sessionId, event)
+    if (!change) return
+    const frame = store.applyTrajectory(sessionId, change)
+    if (!frame) return
+    // 真条目落盘了：活片段的使命结束（它只是「还没落定」的影子，见 feedTrajectoryLive）。
+    if (change.entries.length || change.state) resetLiveThink(sessionId)
+    if (sessionId !== targetSessionId()) return
+    server?.broadcastTrajectory({ sessionId, ...frame })
+  }
+
+  /**
+   * 轨迹的活片段（2026-10-04 用户解禁「流式不做」，仅完整模式消费，别的模式零影响）：
+   * 模型正在想的那一句，从 `agent/assistant-stream` 的 reasoning-delta 里顺出来。
+   *
+   * 边界三条：
+   *   ① **只吃思考**（reasoning-delta）；回答正文（text-delta）一概不用——回答照旧等
+   *      落定才显示，「流式不做」那条裁决只对轨迹的思考片段解禁；
+   *   ② **只推当前绑定的那个会话**，子 Agent 的流不过来（和轨迹增量帧同一个口径）；
+   *   ③ **落盘即清、打断即清**：真条目一到就让位。它是进程本地的，不重放——手机刷新
+   *      后没了就没了，等下一步的片段接着来，不补假的。
+   *
+   * 节流：模型一秒能吐几十个字，250 毫秒一发、尾随必发；第一段立刻发——
+   * 「有没有动静」这件事最要紧的就是第一眼。
+   */
+  const liveThink = new Map()
+  const LIVE_THINK_MS = 250
+
+  /** 「当前这一段」的尾句：压成一行、限 160 字——给人瞄一眼的，不是给人读的。 */
+  function liveThinkDetail(text) {
+    const paragraphs = String(text).split(/\r?\n[\t ]*\r?\n/)
+    const last = paragraphs[paragraphs.length - 1].replace(/\s+/g, ' ').trim()
+    return last.length > 160 ? `${last.slice(0, 159)}…` : last
+  }
+
+  function resetLiveThink(sessionId) {
+    const slot = liveThink.get(sessionId)
+    if (!slot) return
+    if (slot.timer) clearTimeout(slot.timer)
+    liveThink.delete(sessionId)
+    // 只在真露过字之后才喊「清空」——不然每来一次工具调用都白发一帧。
+    if (slot.sent) server?.broadcastTrajectoryLive({ sessionId, detail: '' })
+  }
+
+  function feedTrajectoryLive(sessionId, frame) {
+    if (sessionId !== targetSessionId()) return
+    if (!frame || frame.type !== 'chunk') { resetLiveThink(sessionId); return }
+    const chunk = frame.chunk ?? {}
+    if (chunk.type === 'reasoning-delta' && chunk.text) {
+      let slot = liveThink.get(sessionId)
+      if (!slot) {
+        slot = { text: '', sent: false, at: 0, timer: null }
+        liveThink.set(sessionId, slot)
+      }
+      slot.text += chunk.text
+      const detail = liveThinkDetail(slot.text)
+      const flush = () => {
+        slot.timer = null
+        slot.at = Date.now()
+        slot.sent = true
+        server?.broadcastTrajectoryLive({ sessionId, detail })
+      }
+      if (!slot.sent || Date.now() - slot.at >= LIVE_THINK_MS) {
+        if (slot.timer) { clearTimeout(slot.timer); slot.timer = null }
+        flush()
+      } else if (!slot.timer) {
+        slot.timer = setTimeout(flush, LIVE_THINK_MS - (Date.now() - slot.at))
+        if (slot.timer.unref) slot.timer.unref()
+      }
+      return
+    }
+    // 出现工具调用 = 这一步走到工具了，思考片段到此为止；text-delta 是回答正文，一概不用。
+    if (chunk.type === 'tool-call-delta') resetLiveThink(sessionId)
+  }
+
   ctx.on('session/event', (session, event) => {
     // 子 agent 的会话不进手机——用户遥控的是自己的主会话，不是它派出去的小弟。
     if (session.header?.origin === 'subagent') return
     const sessionId = session.id
 
+    // 执行轨迹：**在所有早退之前**喂一口。下面 `tool/call` 那条分支取完命令原文就 return
+    // 了（审批卡要用），而工具调用正是轨迹的主干——放在这一句之前，它才不会漏掉。
+    feedTrajectory(sessionId, event)
+
     // 手机正在看的这个会话：顺手让它的完整历史保持新鲜（一分钟最多重读一次）。
     // 只对「当前绑定的那一个」做——手机上没在看的会话，读了也没人看，白花 CPU。
     if (sessionId === targetSessionId()) ensureHistory(sessionId)
@@ -1336,6 +1451,7 @@ export function apply(ctx, config = {}) {
         summary: action.summary,
         senderSessionId: action.senderSessionId,
         sessionId,
+        turn: action.turn,
         timestamp: event.time,
       })
       server?.broadcast('state', store.snapshot())
@@ -1358,7 +1474,7 @@ export function apply(ctx, config = {}) {
       // 带上 id：那条也可能是**排队**排进去的，手机上要靠它对上号、标出「排队中」。
       // 时间戳用事件自己的 `time`：硬盘重放出来的那份也是这个 `time`，两边同钟，
       // 合成时才认得出「这条记录里已经有了」，不会接成两条（见 store.pushUser）。
-      store.pushUser({ text: action.text, sessionId, id: action.id, timestamp: event.time })
+      store.pushUser({ text: action.text, sessionId, id: action.id, turn: action.turn, timestamp: event.time })
       server?.broadcast('state', store.snapshot())
       return
     }
@@ -1366,6 +1482,7 @@ export function apply(ctx, config = {}) {
     // action.kind === 'reply'
     store.pushReply({
       text: action.text, sessionId, reason: action.reason, interrupted: action.interrupted,
+      turn: action.turn,
       // 同上：和硬盘那份用同一个钟（事件的 `time`），否则同一条回复会显示两遍。
       timestamp: event.time,
     })
@@ -1387,8 +1504,19 @@ export function apply(ctx, config = {}) {
   ctx.on('agent/status', ({ agent, status }) => {
     const sessionId = agent?.session?.id
     if (!sessionId) return
-    if (agent.session.header?.origin === 'subagent') return
+    if (agent.session.header?.origin === 'subagent') {
+      const parent = agent.session.header?.parentSession
+      if (parent) {
+        subagentCache.delete(parent)
+        store.setSubagentRunning(parent, sessionId, status === 'running')
+        server?.invalidateSubagents?.(parent)
+        server?.broadcast('state', store.snapshot())
+      }
+      return
+    }
     store.setRunning(sessionId, status === 'running')
+    server?.invalidateNavigation?.()
+    server?.broadcast('navigation-refresh', { reason: 'session-status', sessionId })
     broadcastStatus()
   })
 
@@ -1405,15 +1533,20 @@ export function apply(ctx, config = {}) {
    *    子 Agent 的流不往手机上推。
    */
   ctx.on('agent/assistant-stream', ({ agent, frame }) => {
-    // 流式关着：这里直接掉头。手机上只认落定的那条回答，中途一个字都不推。
-    // 为什么关、为什么留着代码，见 STREAMING_ENABLED 的注释。
-    if (!STREAMING_ENABLED) return
-
     const session = agent?.session
     const sessionId = session?.id
     if (!sessionId) return
     if (session.header?.origin === 'subagent') return
 
+    // 轨迹的活片段：完整模式要「正在想的片段一点点顺出来」（2026-10-04 用户解禁，
+    // 只解禁这一处）。它跑在下面那道闸门**之前**——回答的流式照旧关着，两者互不相干：
+    // 这里吃的是 reasoning-delta，text-delta 一个字都不碰。
+    feedTrajectoryLive(sessionId, frame)
+
+    // 流式关着：这里直接掉头。手机上只认落定的那条回答，中途一个字都不推。
+    // 为什么关、为什么留着代码，见 STREAMING_ENABLED 的注释。
+    if (!STREAMING_ENABLED) return
+
     // 只报一次：这条日志回答的是「事件到底有没有送到插件」。一条都没有，就说明
     // 问题在订阅那一层，不用再往下查。
     if (!sawStreamEvent) {
@@ -1483,17 +1616,45 @@ export function apply(ctx, config = {}) {
   // 会话一建出来就登记，这样手机上的会话选择器不用等到有活动才出现。
   ctx.on('agent/created', ({ agent }) => {
     const sessionId = agent?.session?.id
-    if (!sessionId || agent.session.header?.origin === 'subagent') return
+    if (!sessionId) return
+    if (agent.session.header?.origin === 'subagent') {
+      const parent = agent.session.header?.parentSession
+      if (parent) {
+        subagentCache.delete(parent)
+        store.setSubagentRunning(parent, sessionId, agent.status === 'running')
+        server?.invalidateSubagents?.(parent)
+        server?.broadcast('state', store.snapshot())
+      }
+      return
+    }
+    sessionMeta.upsert({ header: agent.session.header, live: true, persisted: false })
     store.touchSession(sessionId, {
       running: agent.status === 'running',
     })
+    server?.invalidateNavigation?.()
+    server?.broadcast('navigation-refresh', { reason: 'session-created' })
     server?.broadcast('state', store.snapshot())
   })
 
   ctx.on('agent/disposed', ({ agent }) => {
     const sessionId = agent?.session?.id
     if (!sessionId) return
+    if (agent.session.header?.origin === 'subagent') {
+      const parent = agent.session.header?.parentSession
+      if (parent) {
+        subagentCache.delete(parent)
+        store.setSubagentRunning(parent, sessionId, false)
+        server?.invalidateSubagents?.(parent)
+        server?.broadcast('state', store.snapshot())
+      }
+      return
+    }
+    sessionMeta.upsert({ header: agent.session.header, live: false, persisted: true })
     store.forgetSession(sessionId)
+    // 轨迹那个累计器也清掉（它有自己的一份 per-session 状态）。
+    trajectory.forget(sessionId)
+    server?.invalidateNavigation?.()
+    server?.broadcast('navigation-refresh', { reason: 'session-disposed' })
     server?.broadcast('state', store.snapshot())
   })
 
@@ -1576,6 +1737,8 @@ export function apply(ctx, config = {}) {
       const events = Array.isArray(snap?.events) ? snap.events : []
       const entries = replayHistory(events)
       const capped = capEntries(entries)
+      // 轨迹和聊天记录是**同一批事件的两面**，顺手一起重放出来；不这样就得为它再读一遍盘。
+      const traj = capTrajectory(replayTrajectory(events))
       return {
         entries: capped.entries,
         latest: lastReply(capped.entries, sessionId),
@@ -1585,6 +1748,10 @@ export function apply(ctx, config = {}) {
         // 于是手机上真看到的条数可能比这里多一两条。数字对不上就是假话，
         // 所以这里只声称**读取的上限**，不声称列表长度。
         note: capped.dropped > 0 ? `只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条）` : null,
+        // 轨迹在**插件这一层就按自己的上限截好**再进缓存：不截的话，20 个会话的缓存会
+        // 各压着几兆（见 lib/store.js 的 setReplaySource 那段说明）。
+        trajectory: traj.turns,
+        trajectoryDropped: traj.dropped,
       }
     } catch (err) {
       // 老日志格式对不上、文件坏了，都会走到这儿。退回「手里那份」，**不编**。
@@ -1623,6 +1790,7 @@ export function apply(ctx, config = {}) {
     const entries = replayHistory(tail.events)
     const capped = capEntries(entries)
     if (!capped.entries.length) return null
+    const traj = capTrajectory(replayTrajectory(tail.events))
     const windowMb = (HISTORY_TAIL_WINDOW_BYTES / 1048576).toFixed(0)
     // 「不是全部」有两处会砍：readTailEvents 那层（窗口 / 事件上限）和这里 capEntries 那层
     // （聊天记录条数上限）。**两层都要算进去**——小会话的窗口盖得住整份日志，唯一会砍它的
@@ -1639,6 +1807,10 @@ export function apply(ctx, config = {}) {
           ? `只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条）`
           : `这个会话很大，只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条 / ${windowMb}MB 窗口）`)
         : null,
+      // 轨迹那一份的「不是全部」由 store 自己说（它知道轨迹的上限），这里只把
+      // 「被砍了多少条」交出去——读取窗口那一层的截断在上面 note 里已经说过一次了。
+      trajectory: traj.turns,
+      trajectoryDropped: traj.dropped,
     }
   }
 
@@ -1687,6 +1859,8 @@ export function apply(ctx, config = {}) {
         latest: got?.latest ?? null,
         truncated: got?.truncated === true,
         note: got?.note ?? null,
+        trajectory: got?.trajectory ?? null,
+        trajectoryDropped: got?.trajectoryDropped ?? 0,
       })
       historyPending.delete(sessionId)
       server?.broadcast('state', store.snapshot())
@@ -1705,6 +1879,10 @@ export function apply(ctx, config = {}) {
         // 这个会话只有这么点内容（读历史有上限，见 HISTORY_MAX_* 那组常量）。
         truncated: hit.truncated === true,
         note: hit.note ?? null,
+        // 同一份记录里重放出来的执行轨迹（「完整」模式要的过程区）。
+        // store 会把它和内存里那份合成一张表，见 store.trajectoryOf。
+        trajectory: hit.trajectory ?? null,
+        trajectoryDropped: hit.trajectoryDropped ?? 0,
       }
     }
     if (historyPending.has(sessionId)) return { entries: null, latest: null, pending: true }
@@ -1816,7 +1994,25 @@ export function apply(ctx, config = {}) {
    * `listDescendants` 读的是父会话自己的目录**事实**，不加载也不唤醒任何子代理——
    * 所以列一下很便宜，也不会把睡着的子代理弄醒。
    */
-  async function listSubagents(parentSessionId) {
+  const subagentMetricInflight = new Map()
+
+  async function fillSubagentMetrics(parentSessionId, rows) {
+    if (subagentMetricInflight.has(parentSessionId)) return
+    const task = (async () => {
+      for (const row of rows) {
+        if (!row || row.diagnostic) continue
+        const metrics = subagentMetrics(row.id)
+        server?.broadcast('subagent-metrics', {
+          parentSessionId,
+          childId: row.id,
+          ...metrics,
+        })
+      }
+    })().finally(() => subagentMetricInflight.delete(parentSessionId))
+    subagentMetricInflight.set(parentSessionId, task)
+  }
+
+  async function readSubagentRows(parentSessionId) {
     const runtime = subagentServices.runtime
     if (!parentSessionId) return { ok: false, error: '手机上还没有绑定会话。' }
     if (typeof runtime?.listDescendants !== 'function') {
@@ -1837,7 +2033,7 @@ export function apply(ctx, config = {}) {
         out.push({ id: String(row.id), diagnostic: String(row.reason ?? 'unavailable') })
         continue
       }
-      const metrics = subagentMetrics(row.id)
+      const metrics = { tokens: null, durationMs: null, lastTurnCompleted: null }
       out.push({
         id: String(row.id),
         parentId: String(row.parentId ?? ''),
@@ -1854,6 +2050,25 @@ export function apply(ctx, config = {}) {
     return { ok: true, subagents: out, boundSessionId: parentSessionId }
   }
 
+  async function listSubagents(parentSessionId, { includeMetrics = true, scheduleMetrics = false } = {}) {
+    if (!parentSessionId) return readSubagentRows(parentSessionId)
+    const cached = !includeMetrics ? subagentCache.get(parentSessionId) : null
+    const rows = cached
+      ? { ok: true, subagents: cached, boundSessionId: parentSessionId }
+      : await readSubagentRows(parentSessionId)
+    if (!rows.ok) return rows
+    if (includeMetrics) {
+      rows.subagents = rows.subagents.map((row) => row.diagnostic
+        ? row
+        : { ...row, ...subagentMetrics(row.id) })
+    }
+    if (!cached) subagentCache.set(parentSessionId, rows.subagents)
+    if (scheduleMetrics && !includeMetrics) {
+      setTimeout(() => { fillSubagentMetrics(parentSessionId, rows.subagents) }, 0).unref?.()
+    }
+    return rows
+  }
+
   /**
    * 某个子智能体**自己的运行过程**。
    *
@@ -1865,7 +2080,7 @@ export function apply(ctx, config = {}) {
    */
   async function subagentTranscript(childId, parentSessionId) {
     if (!childId) return { ok: false, error: '没说要读哪一道子智能体。' }
-    const listed = await listSubagents(parentSessionId)
+    const listed = await listSubagents(parentSessionId, { includeMetrics: false, scheduleMetrics: false })
     if (!listed.ok) return listed
     const row = listed.subagents.find((s) => s.id === childId)
     if (!row) return { ok: false, error: '这道子智能体不在当前会话名下。' }
@@ -2162,6 +2377,84 @@ export function apply(ctx, config = {}) {
       + Boolean(canCreate.controller) + ' create=' + typeof canCreate.controller?.create)
   })
 
+  // Agent 模式注册表（2026-10-04 用户要求：新建会话时手机上也要能选模式，PC 一直
+  // 可以）。**单独 inject**（理由同上：缺一个服务不该连别的都没了）。没有它的时候
+  // 手机直接建 DSH 的默认模式，如实说「没有可选的」——不摆一个没得选的选择题。
+  const canPresets = { registry: null }
+  ctx.inject(['agentPresets'], (presetsCtx) => {
+    canPresets.registry = presetsCtx.agentPresets
+    console.log('[dsh-mini-remote] Agent 模式清单已就绪：agentPresets=' + Boolean(canPresets.registry))
+  })
+
+  // 插件管理服务（手机端「插件」页面用）。
+  const pluginServices = { manager: null }
+  // DSH 版本号问到一次就记着（版本不会中途变），省得每 30 秒问一趟。
+  let cachedDshVersion = ''
+  ctx.inject(['pluginManager'], (pCtx) => {
+    pluginServices.manager = pCtx.pluginManager
+    console.log('[dsh-mini-remote] 插件管理服务已就绪：pluginManager=' + Boolean(pluginServices.manager))
+  })
+
+  /**
+   * 「内置插件」要用的两样东西（2026-10-04 用户指出：内置插件只显示 6 个是不对的）。
+   *
+   * DSH 的理念是「一切皆插件、无特权核心」——一整套系统是几百个插件模块拼起来的，
+   * 所以「内置插件」的真相不在 npm 包清单里（那是「插件市场」的粒度），
+   * 而在 **Cordis Loader 的实时条目表**里。PC 的「设置 → 内置插件」页读的正是它，
+   * 分成两块：全局插件（系统与所有会话共用）+ 会话插件（按 Agent 预设组合而成）。
+   *
+   * 两样都走 ctx.inject（软注入）：拿不到就只少这一块，不整个倒下。
+   * `pluginPackages` 只提供显示用的本地化标题/说明，没有它照样能列出来（退成模块名）。
+   */
+  const invServices = { loader: null, packages: null, settings: null }
+  ctx.inject(['loader'], (lCtx) => {
+    invServices.loader = lCtx.loader
+    console.log('[dsh-mini-remote] Cordis Loader 已就绪（内置插件清单要用）：loader='
+      + Boolean(invServices.loader))
+  })
+  ctx.inject(['pluginPackages'], (pkCtx) => {
+    invServices.packages = pkCtx.pluginPackages
+    console.log('[dsh-mini-remote] 插件包元数据已就绪：pluginPackages='
+      + Boolean(invServices.packages))
+  })
+  // 设置文档：问「官方插件里注册了设置卡片的那几个，这台部署是不是提供了」。
+  ctx.inject(['settings'], (sCtx) => {
+    invServices.settings = sCtx.settings
+    console.log('[dsh-mini-remote] 设置文档已就绪（官方插件卡片要用）：settings='
+      + Boolean(invServices.settings))
+  })
+
+  /**
+   * 官方插件里「注册了一张设置卡片」的那几个。
+   *
+   * **为什么只能列在这里**：这几张卡片是**浏览器端**的插件在运行时注册进 Plugins 页的
+   * `plugins.item` 插槽的（dsh-client-ui-plugin-manager 读的是 `ctx.slots`），
+   * 宿主进程看不见浏览器里的插槽注册表——没有哪条宿主接口能问出来。
+   * 所以包 identity、卡片 id、开关注册所用的命名空间、中文文案，
+   * 只能照 DSH 0.2.0-rc.2 的客户端源码抄一份（4 个包各注册一张卡）：
+   *
+   *   dsh-client-ui-settings-shell        id=shell       等 bash-sandbox / pwsh-sandbox
+   *   dsh-client-ui-settings-agent-loop   id=agent-loop  等 agent-loop
+   *   dsh-client-ui-settings-subagent     id=subagent    等 subagent / subagent-model-selection-settings
+   *   dsh-client-ui-settings-web-search   id=web-search  等 web-search-deepseek
+   *
+   * 文案逐字取自那几个包 `lib/client.js` 里自己的 zh 词典（不自己编）。
+   *
+   * **出现条件照 DSH 同一条规矩**：宿主的设置文档里 served 了它那几个命名空间才出现
+   * （DSH 那边是 `configForms.whileServed(namespaces, …)`）——所以「这台部署没有终端设置」
+   * 时，手机上也不会凭空多出一张终端卡。DSH 以后再加官方卡片，这张表要跟着补。
+   */
+  const OFFICIAL_CARDS = [
+    { id: 'shell', namespaces: ['bash-sandbox', 'pwsh-sandbox'], title: '终端',
+      description: '限制每条命令最多能跑多久、最多输出多少内容。' },
+    { id: 'agent-loop', namespaces: ['agent-loop'], title: 'Agent 循环',
+      description: '控制 Agent 派发工具调用的方式。' },
+    { id: 'subagent', namespaces: ['subagent', 'subagent-model-selection-settings'], title: '子智能体',
+      description: '设置子智能体的递归层级、数量和模型。' },
+    { id: 'web-search', namespaces: ['web-search-deepseek'], title: '网页搜索',
+      description: '设置 DeepSeek 的搜索提供方。' },
+  ]
+
   // ------------------------------------------------------------------
   // 手机上传文件要用的附件服务
   // ------------------------------------------------------------------
@@ -2333,9 +2626,54 @@ export function apply(ctx, config = {}) {
     }
   }
 
+  /**
+   * 取一份「本地化文案」里的中文。
+   *
+   * 形状是 LocalizedText：一个字符串，或 `{ en, 'zh-CN', … }` 这种按语言分份的对象。
+   * 插件的标题和说明都是这个形状——不挑语言直接读，官方插件在手机上就全是英文。
+   * 没有中文退英文，再没有就取第一个非空串；都没有返回空串（调用方自己决定怎么兜）。
+   */
+  function localizedText(v) {
+    if (typeof v === 'string') return v
+    if (!v || typeof v !== 'object') return ''
+    for (const k of ['zh-CN', 'zh-Hans', 'zh', 'en']) {
+      if (typeof v[k] === 'string' && v[k]) return v[k]
+    }
+    for (const val of Object.values(v)) if (typeof val === 'string' && val) return val
+    return ''
+  }
+
+  /**
+   * Loader 条目的 Fiber 状态码 → 词。照 dsh-host-plugin-inventory 里那张表：
+   * 0 待定 / 1 加载中 / 2 运行中 / 3 失败 / 4 已销毁（报 null）/ 5 卸载中。
+   */
+  const FIBER_PHASE = ['pending', 'loading', 'active', 'failed', null, 'unloading']
+
+  /**
+   * 一个 Agent 模式（预设）拿给用户看的名字与说明。
+   *
+   * 政策照 PC：**声明里自带名字的（自建模式）用它自己的**，没名字的（内置那几档）
+   * 才落 AGENT_MODE_COPY；认不出又没名字的落 null——如实，不瞎起名。
+   *
+   * 抽出来是因为两处要用：手机上「选模式」的清单，以及插件页「会话插件」按预设分组。
+   * （2026-10-05 实测抓到：分组那儿漏了这一步，页面上露出 standard / ptc / cordis
+   * 这种英文代号——组合清单里的 name 是预设声明的原名，不是给用户看的名字。）
+   */
+  function presetCopyOf(p) {
+    const copy = AGENT_MODE_COPY[p?.id]
+    const hasName = typeof p?.name === 'string' && p.name
+    const hasDesc = typeof p?.description === 'string' && p.description
+    return {
+      id: p?.id,
+      name: hasName ? p.name : (copy ? copy[0] : null),
+      description: hasDesc ? p.description : (copy ? copy[1] : null),
+      broken: typeof p?.broken === 'string' ? p.broken : null,
+    }
+  }
+
   const nav = {
     listWorkspaces: (runningIds, force, includeEmpty) =>
-      listWorkspaces({ registry: treeServices.registry, query: treeServices.query, runningIds, force, includeEmpty }),
+      listWorkspaces({ registry: treeServices.registry, query: treeServices.query, runningIds, force, includeEmpty, meta: sessionMeta }),
     listSessionsOf: (workspaceId, limit, force, onTitle) =>
       listSessionsOf({
         registry: treeServices.registry,
@@ -2347,15 +2685,38 @@ export function apply(ctx, config = {}) {
         limit,
         force,
         onTitle,
+        meta: sessionMeta,
       }),
     // 建会话：先用 inject 拿到的那个，拿不到就现读一次——`ctx.get` 对没写进 inject
     // 的服务名是**返回 undefined**（不是抛错），所以这么写是安全的。
-    createSession: (workspaceId) =>
+    createSession: (workspaceId, agentPreset) =>
       createSessionIn({
         controller: canCreate.controller ?? ctx.get('sessionController'),
         registry: treeServices.registry,
         workspaceId,
+        agentPreset,
       }),
+    // Agent 模式清单（2026-10-04）：手机新建会话时挑模式用。坏档也如实给（broken），
+    // 拿不到能力就说 unavailable——不摆一个没得选的选择题。默认哪一档由
+    // registry 的 defaultId 说（那是 DSH 自己的默认，不猜）。
+    //
+    // 名字照抄 PC 的词条表（见 AGENT_MODE_COPY，用户 2026-10-04 点名「模式选择应该
+    // 为中文」）。政策也照 PC：**声明里自带名字的（自建模式）用它自己的**，没名字的
+    // （内置档）才落词条表；认不出又没名字的才落 id——如实，不瞎起名。
+    agentPresets: async () => {
+      const svc = canPresets.registry ?? ctx.get('agentPresets')
+      if (!svc || typeof svc.list !== 'function') return { ok: false, reason: 'unavailable' }
+      try {
+        const list = await svc.list()
+        return {
+          ok: true,
+          defaultId: typeof svc.defaultId === 'string' ? svc.defaultId : null,
+          presets: (Array.isArray(list) ? list : []).map(presetCopyOf),
+        }
+      } catch (err) {
+        return { ok: false, reason: 'failed', error: String(err?.message ?? err) }
+      }
+    },
     // 「这一刻到底能不能建会话」。给 /mini/api/version 用：那是个不用动手、
     // 一条命令就能问的运行时事实，比翻日志快。和 createSession 同一条判据，
     // 免得出现「探测说能、真按了却不行」。
@@ -2374,7 +2735,302 @@ export function apply(ctx, config = {}) {
 
     // 子智能体（2026-10-03）。四条都取**当前绑定会话**那一份，和上面 send / stop
     // 同一套口径：手机上遥控的是你正看着的那个会话，不该牵动你在电脑上另开的那个。
-    subagents: (sessionId) => listSubagents(sessionId),
+    subagents: (sessionId, options) => listSubagents(sessionId, options),
+
+    /**
+     * 插件清单（手机端「插件」页面用，2026-10-04）。
+     *
+     * 字段照 DSH 的 `BundleInfo`（pluginManager 的契约，逐字段对过）：
+     *   name / version / installed / optional / enabled / description
+     *   meta: { title?, description? } —— **本地化文案**，中文说明在这一份里；
+     *   error: { code, diagnostic? } —— 出问题的那一笔。
+     *
+     * 两处不照抄会难看：① 只取 `description`（包的英文说明），
+     * PC 上那句中文「启用团队协作、团队工具……」来自 `meta.description`，得优先用它；
+     * ② `error` 是个对象，直接递出去页面上会显示 `[object Object]`。
+     */
+    /**
+     * 正在跑的这只 DSH 是哪个版本（设置页底部那行用，2026-10-04）。
+     *
+     * **为什么不读文件**：早先这里去翻 `node_modules/@deepseek-ai/dsh/package.json`，
+     * 两个毛病都踩了——① 那是「命令行那份 dsh」的版本，未必等于正在跑的这只 Host
+     * （实测桌面端跑的是 0.2.0-rc.2，而命令行那份写着 0.2.0-rc.1）；
+     * ② 桌面端的工作目录里压根没有那个文件，于是手机上一直显示 `unknown`。
+     *
+     * 改问正在跑的这只 Host：它自己报的运行时版本才作数。问到一次就记住。
+     */
+    dshVersion: async () => {
+      if (cachedDshVersion) return cachedDshVersion
+      const mgr = pluginServices.manager ?? ctx.get('pluginManager')
+      try {
+        // 这个接口本意是列「版本豁免」，但它捎带把运行时版本报出来了
+        // ——宿主唯一一处直接说「我是哪个版本」的地方。
+        const got = await mgr?.listVersionExemptions?.()
+        if (typeof got?.runtimeVersion === 'string' && got.runtimeVersion) {
+          cachedDshVersion = got.runtimeVersion
+          return cachedDshVersion
+        }
+      } catch (err) {
+        // 问不到就往下一步退，不把设置页那行弄崩。
+      }
+      try {
+        // 退一步：核心包自己的版本就是 DSH 的版本（整个仓库一起发版）。
+        const bundles = await mgr?.listBundles?.()
+        const base = (bundles || []).find((b) => b?.name === '@deepseek-ai/dsh-base')
+        if (typeof base?.version === 'string' && base.version) {
+          cachedDshVersion = base.version
+          return cachedDshVersion
+        }
+      } catch (err) {
+        // 都没有就如实说不知道（页面据此整行不显示，不拿 unknown 糊一行）。
+      }
+      return 'unknown'
+    },
+
+    pluginList: async () => {
+      const mgr = pluginServices.manager ?? ctx.get('pluginManager')
+      if (!mgr) return { ok: false, reason: 'unavailable' }
+      try {
+        const bundles = await mgr.listBundles()
+        return {
+          ok: true,
+          bundles: (bundles || []).map((b) => ({
+            name: b?.name ?? '',
+            // 显示名优先用本地化标题（官方插件在 PC 上显示的是「智能体团队」而不是包名），
+            // 没有就退回包名——第三方插件多半没有标题。
+            title: localizedText(b?.meta?.title) || b?.name || '',
+            description: localizedText(b?.meta?.description) || b?.description || '',
+            version: typeof b?.version === 'string' ? b.version : '',
+            installed: b?.installed === true,
+            optional: b?.optional === true,
+            enabled: b?.enabled !== false,
+            // 出问题的那一笔：有原话就说原话，没有就报错误码。没它就别硬编。
+            problem: b?.error ? (b.error.diagnostic || b.error.code || '有问题') : '',
+          })),
+        }
+      } catch (err) {
+        return { ok: false, reason: String(err?.message || err) }
+      }
+    },
+
+    /**
+     * 内置插件清单（手机端「插件 → 已安装 → 内置」用，2026-10-04 补）。
+     *
+     * **为什么不是 listBundles**：那是 npm 包的粒度（十几个），答不了「内置插件有多少」。
+     * DSH 是「一切皆插件、无特权核心」，一整套系统由几百个插件模块拼成，真相在
+     * Cordis Loader 的实时条目表里。PC 的「设置 → 内置插件」页就是读这里，分两块：
+     *   全局插件 = Loader 自己的条目（系统与所有会话共用）；
+     *   会话插件 = 各 Agent 预设的组合行（预设挂载后才在会话里跑）。
+     *
+     * 读取逻辑照 `dsh-host-plugin-inventory`（那是只读投影，我们直接读同几个源：
+     * loader.entries() / agentPresets.compositionInventory() / pluginPackages.metaOf()），
+     * 因为它在宿主服务目录里查不到，只能按它的实现来。
+     */
+    pluginInventory: async () => {
+      const loader = invServices.loader ?? ctx.get('loader')
+      if (!loader || typeof loader.entries !== 'function') {
+        return { ok: false, reason: 'unavailable' }
+      }
+      const packages = invServices.packages ?? ctx.get('pluginPackages')
+      // 显示用的本地化元数据。取不到就是没有——退成模块名，不影响列出来。
+      const metaOf = (moduleName, base) => {
+        if (!packages || typeof packages.metaOf !== 'function' || base === undefined) return null
+        try {
+          return packages.metaOf(moduleName, base) ?? null
+        } catch (err) {
+          return null
+        }
+      }
+      /**
+       * 模块名压成短名。照 PC 的「内置插件」面板（dsh-client-ui-settings-plugin-inventory
+       * 里那个 moduleShortName）：`@deepseek-ai/dsh-tool-fs` → `tool-fs`。
+       * 手机上不压的话每一行都是 `@deepseek-ai/dsh-xxx`，一屏放不下几个。
+       */
+      const shortName = (name) => String(name ?? '')
+        .replace(/^@[^/]+\//, '')
+        .replace(/^cordis:/, '')
+        .replace(/^cordis-plugin-/, '')
+        .replace(/^dsh-(?:host-|client-)?/, '')
+      /**
+       * 显示名。PC 的规矩：`meta.title` 是本地化对象就取文案，否则把那一份
+       * （字符串标题，或干脆是模块名）压成短名。没有标题就退到模块名的短名。
+       */
+      const titleOf = (meta, moduleName) => {
+        const t = meta?.title
+        if (t && typeof t === 'object') return localizedText(t) || shortName(moduleName)
+        return shortName(t || moduleName)
+      }
+      const rowOf = (moduleName, base, extra) => {
+        const meta = metaOf(moduleName, base)
+        return {
+          entryId: extra.entryId,
+          moduleName,
+          title: titleOf(meta, moduleName),
+          description: localizedText(meta?.description),
+          enabled: extra.enabled,
+          // 预设组合行可能是 'conditional'（带 !!js 条件、要挂载后才定得下来）。
+          conditional: extra.conditional === true,
+          condition: extra.condition,
+          phase: extra.phase,
+        }
+      }
+
+      const entries = []
+      try {
+        for (const entry of loader.entries()) {
+          // 分组只是树上的容器，不是插件（PC 的内置插件页同样跳过它们）。
+          if (entry?.options?.group) continue
+          const moduleName = String(entry?.options?.name ?? '')
+          entries.push(rowOf(moduleName, entry?.parent?.tree?.ctx?.baseUrl, {
+            entryId: String(entry?.id ?? ''),
+            enabled: entry?.disabled !== true,
+            condition: '',
+            phase: entry?.fiber === undefined ? null : (FIBER_PHASE[entry.fiber.state] ?? null),
+          }))
+        }
+      } catch (err) {
+        return { ok: false, reason: '读 Loader 条目失败：' + String(err?.message || err) }
+      }
+
+      // 会话插件：预设的组合行。拿不到就空着——那说明这个部署没挂预设名册，
+      // 不是「一个都没有」，所以页面那一块整块不画。
+      const presets = []
+      try {
+        const registry = canPresets.registry ?? ctx.get('agentPresets')
+        // 组合清单里的 `name` 是预设自己声明的**原名**（内置那几档就是 standard / ptc
+        // 这种代号），不是给用户看的。给用户看的名字在名册那边——走和「选模式」同一套
+        // 政策取（见 presetCopyOf）。名册读不到就退到原名，不硬编一张对照表。
+        const shownName = new Map()
+        try {
+          const roster = await registry?.list?.()
+          for (const p of Array.isArray(roster) ? roster : []) {
+            const copy = presetCopyOf(p)
+            if (copy.id !== undefined && copy.name) shownName.set(String(copy.id), copy.name)
+          }
+        } catch (err) {
+          // 名册问不到不影响列出组合（只是名字会退回代号）。
+        }
+        const list = await registry?.compositionInventory?.()
+        for (const one of list || []) {
+          const id = String(one?.id ?? '')
+          presets.push({
+            id,
+            name: shownName.get(id) || localizedText(one?.name) || id,
+            isDefault: one?.isDefault === true,
+            broken: one?.broken ? String(one.broken) : '',
+            rows: (one?.rows || []).map((r) => rowOf(String(r?.moduleName ?? ''), ctx.baseUrl, {
+              entryId: r?.entryId === null || r?.entryId === undefined ? '' : String(r.entryId),
+              enabled: r?.enabled === true,
+              conditional: r?.enabled === 'conditional',
+              condition: r?.condition ? String(r.condition) : '',
+              phase: r?.fiberState === undefined ? null : (FIBER_PHASE[r.fiberState] ?? null),
+            })),
+          })
+        }
+      } catch (err) {
+        // 预设读不动不该把全局那一半也拖没：两块各报各的。
+        console.log('[dsh-mini-remote] 预设组合读不到（内置插件的会话那一块会空着）：'
+          + String(err?.message || err))
+      }
+
+      return { ok: true, entries, presets, hasRoster: canPresets.registry !== null }
+    },
+
+    /**
+     * 官方插件里那几张「设置卡片」（2026-10-04 用户确认：官方就是这 8 个，手机上也要看得到）。
+     *
+     * 官方那一栏其实是两样东西拼的，PC 上也是：
+     *   ① 可开关的官方插件**包**（optional && 未装）——走 pluginList，4 个；
+     *   ② 注册了设置卡片的官方插件——就是这里，4 个（终端 / Agent 循环 / 子智能体 / 网页搜索）。
+     * 两张合起来正好是 PC 上那 8 个。
+     *
+     * 判据照 DSH：宿主的设置文档 served 了卡片那几个命名空间才出现。问不到设置文档时
+     * **整块不出现**（宁可少画，不凭空多画）——这和 DSH 自己「不 served 就不注册」一致。
+     */
+    officialPlugins: async () => {
+      const settings = invServices.settings ?? ctx.get('settings')
+      if (!settings || typeof settings.describe !== 'function') return { ok: true, cards: [] }
+      let served = null
+      try {
+        served = new Set((settings.describe() || []).map((d) => String(d?.ns ?? '')))
+      } catch (err) {
+        return { ok: false, reason: String(err?.message || err) }
+      }
+      return {
+        ok: true,
+        cards: OFFICIAL_CARDS
+          .filter((c) => c.namespaces.some((n) => served.has(n)))
+          .map((c) => ({ kind: 'card', id: c.id, title: c.title, description: c.description })),
+      }
+    },
+    /**
+     * 「繁忙时的发送行为」（2026-10-05 用户要求搬进手机设置）。
+     *
+     * **这是什么**：智能体正在跑的时候，你在手机上进的那句话到底怎么交给它——
+     *   排队发送（queue）：排到队尾，等当前这一轮跑完再跑；
+     *   插话发送（steer）：直接插进去，它当场看到并调整方向。
+     *
+     * **PC 上是同一个东西**：设置 → 通用里的「繁忙时的发送行为」。
+     * 真相在 `dsh-client-ui-conversation` 里：
+     *   命名空间 ui-conversation、字段 busyEnter、取值 queue|steer、默认 queue。
+     *   它的注释原话是「Busy-Enter preference shared by the composer bar inject face
+     *   and its Settings row: one live store … backed by the Host user-settings document」。
+     *
+     * **两端共用一个值**（用户 2026-10-05 拍板「都 ok」）：宿主只有一份用户设置文档，
+     * 手机上改它，电脑上也是这个值。这样才不会出现「手机上选了插话、电脑上还是排队」。
+     *
+     * **拿不到就整条不显示**，不摆一个假的开关——和插件页那套「宁可少画」同一口径。
+     */
+    busyEnterSetting: async () => {
+      const settings = invServices.settings ?? ctx.get('settings')
+      if (!settings || typeof settings.describe !== 'function') return { ok: false, reason: 'unavailable' }
+      let doc = null
+      try {
+        doc = (settings.describe() || []).find((d) => String(d?.ns ?? '') === 'ui-conversation') ?? null
+      } catch (err) {
+        return { ok: false, reason: String(err?.message || err) }
+      }
+      // 这个命名空间得真的被 served 才有得改——没有它就没有这一条。
+      if (!doc) return { ok: false, reason: 'unavailable' }
+      const value = doc?.value && typeof doc.value === 'object' ? doc.value : {}
+      const current = value.busyEnter === 'steer' ? 'steer' : 'queue'
+      return {
+        ok: true,
+        current,
+        // 带上 revision：写的时候要它做乐观锁，免得和电脑上同时改打架。
+        revision: typeof doc.revision === 'number' ? doc.revision : undefined,
+      }
+    },
+
+    /**
+     * 改「繁忙时的发送行为」。值只有两个，别的一律拒绝——**不替用户猜一个**。
+     *
+     * 走 `settings.update(ns, patch, revision)`（官方契约里的「把一个 entry 的可编辑
+     * 字段合并进去」）。带 revision 是有意的：万一电脑上刚改过，这次写入会被挡下来
+     * 而不是把对方的改动盖掉——那种覆盖用户看不见，最难查。
+     */
+    setBusyEnter: async (next) => {
+      if (next !== 'queue' && next !== 'steer') {
+        return { ok: false, reason: 'invalid' }
+      }
+      const settings = invServices.settings ?? ctx.get('settings')
+      if (!settings || typeof settings.update !== 'function') return { ok: false, reason: 'unavailable' }
+      let revision
+      try {
+        const doc = (settings.describe() || []).find((d) => String(d?.ns ?? '') === 'ui-conversation')
+        if (!doc) return { ok: false, reason: 'unavailable' }
+        revision = typeof doc.revision === 'number' ? doc.revision : undefined
+      } catch (err) {
+        return { ok: false, reason: String(err?.message || err) }
+      }
+      try {
+        await settings.update('ui-conversation', { busyEnter: next }, revision)
+      } catch (err) {
+        return { ok: false, reason: String(err?.message || err) }
+      }
+      return { ok: true, current: next }
+    },
+
     subagentTranscript: (childId, sessionId) => subagentTranscript(childId, sessionId),
     stopSubagent: (childId, sessionId, mode) => stopSubagent(childId, sessionId, mode),
     askSubagent: (childId, sessionId, mode, text) => askSubagent(childId, sessionId, mode, text),