dsh-mini-remote 0.1.7 → 0.1.8

package/lib/index.js

@@ -37,6 +37,7 @@ import {
 } from './commands.js'
 import { createMiniServer, miniControl, sendJson, readBody } from './server.js'
 import { sendExternalNotification } from './notify.js'
+import { createFeishuChannel, feishuQuestionText, approvalText, FEISHU_TEXT_LIMIT } from './lark.js'
 import { reachableAddresses, resolveBindAddresses, isLocalRequest } from './net.js'
 import { buildPairing, tunnelUrlFor, tunnelProbeVerdict } from './pairing.js'
 import { serveState, serveEnable, serveDisable } from './serve.js'
@@ -68,6 +69,15 @@ const TUNNEL_ATTEMPTS = 3
  */
 const MAX_PENDING_UPLOADS = 20
 
+/**
+ * 飞书里发 `/会话` 最多列几个会话。
+ *
+ * 10 是「一屏能看完」定的：手机页是把工作区一层层展开看的，飞书里只有一条消息，
+ * 列太长要划半天，而这条命令要的只是「切到那一个」。超出的部分如实说还剩多少条
+ * （见 lib/lark.js 的 sessionPickText）。
+ */
+const FEISHU_PICK_MAX = 10
+
 /**
  * 这份代码的构建指纹，加载时算一次。
  * 用来回答「现在应答我的进程，跑的是不是我改的这份代码」——重启期间旧进程还在
@@ -112,6 +122,22 @@ const DEFAULTS = {
     maxLength: 200,
     sound: 'default',
   },
+  /**
+   * 飞书通路（长连接）。默认关。
+   *
+   * 为什么默认关：开了之后这台电脑就多了一扇「从飞书进来的门」，该由用户自己决定。
+   * 而且**两个名单都空 = 谁都不认**（判据在 lib/lark.js 的 admitSource）——门开着但
+   * 名单不填，等于开着没钥匙，这是刻意的默认值。
+   */
+  feishu: {
+    enabled: false,
+    appId: '',
+    appSecret: '',
+    /** 允许的 open_id，一行一个（逗号、分号也行）。空 = 这份名单不设限。 */
+    openIds: '',
+    /** 允许的 chat_id，同上。两个都空 = 任何来源都不处理。 */
+    chatIds: '',
+  },
 }
 
 /**
@@ -166,6 +192,23 @@ export const Config = z.object({
     maxLength: z.number(),
     sound: z.string(),
   })).description('外部推送（Bark / ntfy / Telegram）。改了立即生效，不用重载。'),
+  /**
+   * 飞书这一块**没有**标 volatile（口径见上面那段注释）。
+   *
+   * 这不是省事：飞书的长连接是用 appId/appSecret 建起来的，改了凭据就得把那条连接
+   * 整个换掉——那一步不是「就地改一个值」能兑现的。标了 volatile 等于向 DSH 承诺
+   * 「改它不用重载」，而承诺得在代码里兑现。**宁可少标，不能乱标。**
+   *
+   * 用户实际不会因此多做什么：设置页那一页有自己的保存按钮，存完插件自己就会把连接
+   * 换掉（见 restartFeishu）。只有手改 settings.json 的人需要重载一次插件。
+   */
+  feishu: z.object({
+    enabled: z.boolean(),
+    appId: z.string(),
+    appSecret: z.string().role('secret'),
+    openIds: z.string(),
+    chatIds: z.string(),
+  }).description('飞书（长连接）：机器人的两个凭据与两个允许名单。改了要重载插件（凭据变了得重建连接）。'),
 })
 
 function deepMerge(base, ...overrides) {
@@ -660,6 +703,185 @@ export function apply(ctx, config = {}) {
     })
   }
 
+  // ------------------------------------------------------------------
+  // 飞书通路（长连接）
+  // ------------------------------------------------------------------
+  /**
+   * 飞书那条路：入站走官方 SDK 的 WebSocket 长连接（不需要公网地址、不需要域名），
+   * 出站用「回复某条消息」接口挂回原消息下。实现全在 lib/lark.js，这里只管它的生死。
+   */
+  /** @type {Awaited<ReturnType<typeof createFeishuChannel>> | null} */
+  let feishu = null
+  /** 正在建连接；用来挡住「连点两次开关起出两条」。 */
+  let feishuStarting = false
+  /** 上一次没起来的原因；null = 没出错。和 serverError 一样，用来把「还没连上」和「起不来」分开说。 */
+  let feishuError = null
+
+  async function bringFeishuUp() {
+    if (feishu || feishuStarting) return
+    const cfg = settings.feishu ?? {}
+    if (!cfg.enabled) return
+    feishuStarting = true
+    feishuError = null
+    try {
+      feishu = await createFeishuChannel({
+        config: cfg,
+        log,
+        onInstruction,
+        // 飞书里回了「同意／1」这类话，交回电脑。走的是手机页同一份清单、同一个 settle
+        // （见 lib/server.js 的 answerQuestion / decideApproval），谁先答谁生效。
+        onAnswer: answerFromFeishu,
+        // `/会话` 要的两件事：列可选会话（标题是手机页同一份缓存）、切到某一个
+        // （切的是手机页同一个全局绑定，切完手机页跟着变）。文案全在 lib/lark.js。
+        listSessions: feishuSessionList,
+        bindSession: bindSessionForFeishu,
+      })
+      log.info('飞书：通路挂上了，等消息。')
+    } catch (err) {
+      feishu = null
+      feishuError = err?.message ?? String(err)
+      log.warn(`飞书没起来：${feishuError}`)
+    } finally {
+      feishuStarting = false
+    }
+  }
+
+  function bringFeishuDown() {
+    feishu?.close()
+    feishu = null
+    feishuError = null
+  }
+
+  /**
+   * 换配置就地重建。
+   *
+   * 长连接是绑在凭据上的，改一处就得整条换掉——所以不是「改个值」而是「关了重开」。
+   * 关这一步必须真的断干净（`close()` 里连定时器一起收），否则会留下一条看不见的
+   * 旧连接，用旧凭据继续收消息。
+   */
+  async function restartFeishu() {
+    bringFeishuDown()
+    await bringFeishuUp()
+  }
+
+  /**
+   * 这条会话叫什么。给飞书那行「会话：…」标记用（见 lib/lark.js 的 sessionTagLine）。
+   *
+   * 来源就是**手机页显示的那个名字**：lib/title-cache.js 那份落盘缓存。取不到就回空串，
+   * 标记那边会写成「未命名会话」——**不把会话 id 露出去**，手机上从不显示 id，
+   * 用户拿着它没有地方可以对。
+   */
+  function titleOfSession(sessionId) {
+    if (!sessionId) return ''
+    const known = titles.get(sessionId)
+    return typeof known === 'string' ? known : ''
+  }
+
+  /**
+   * 这一轮落定的回答，回给在飞书里发指令的那个人。
+   *
+   * **归属靠 sessionId**（见 lib/lark.js 的 takeTarget / markRoundStarted）：哪条会话
+   * 这一轮是从飞书起跑的，回答就回那条飞书消息。`meta.userText` 是这一轮**用户的原话**，
+   * 只做兜底比对——它会被同一轮里后来的一句人话顶掉，所以不能当主凭据。
+   * 手机发起的轮次在这里天然落空——对不上号就不发，不会把手机上的回答倒进飞书。
+   *
+   * 顺带把这条会话的名字一起交出去：飞书那边要在回答末尾补一行「会话：…」。
+   * 只有飞书这条路拿得到它——手机页那份文本一个字都不变。
+   */
+  function onReply(text, meta) {
+    if (!feishu) return
+    // reply() 自己把失败写进日志并返回 { ok:false }，不会抛——这里不用再兜一层。
+    feishu.reply(text, { ...meta, sessionTitle: titleOfSession(meta?.sessionId) })
+  }
+
+  /**
+   * 飞书那边拍完板，把结果交回电脑。
+   *
+   * **这里不判「这道题还在不在」**：那份清单和 settle 都在 lib/server.js，交回去的时候
+   * 它还在不在，由它如实回答（`expired` = 手机先拍了板）。这边只是把飞书的说法翻译成
+   * 那个入口收的形状。
+   *
+   * 末尾那个 `'feishu'` 是**说出来源**，只用来让手机页那张还挂着的卡片知道该收起来、
+   * 该写「已在飞书答过」（见 lib/server.js 的 notifySettled）。不是身份判据。
+   *
+   * @param {{kind: string, id: string, cancel?: boolean, answers?: Array, decision?: string}} reply
+   * @returns {{ok: boolean, error?: string}}
+   */
+  function answerFromFeishu(reply) {
+    const take = reply?.kind === 'approval' ? miniControl.decideApproval : miniControl.answerQuestion
+    if (typeof take !== 'function') return { ok: false, error: 'no-channel' }
+    const input = reply?.cancel === true
+      ? { cancel: true }
+      : (reply?.kind === 'approval' ? { decision: reply?.decision } : { answers: reply?.answers })
+    return take(reply?.id, input, 'feishu')
+  }
+
+  /**
+   * `/会话` 要列的那些：这台电脑上的会话，新的在前。
+   *
+   * 标题走的是**手机页同一份东西**：`nav.listSessionsOf` 拿的正是手机页展开工作区时那份
+   * （knownTitles + 落盘缓存 lib/title-cache.js），取不到就是空串，飞书那边写「未命名会话」。
+   *
+   * 上限是给「一屏能看完」定的，不是给性能定的：工作区一多，全列出来在手机上要划半天。
+   * `total` 一起交出去，好在超出时如实说「只列了最近 N 条」。
+   */
+  async function feishuSessionList() {
+    const workspaces = await nav.listWorkspaces(new Set(), false, false)
+    const rows = []
+    let total = 0
+    for (const ws of workspaces) {
+      const got = await nav.listSessionsOf(ws.id, FEISHU_PICK_MAX, false)
+      if (!got) continue
+      total += Number(got.total) || 0
+      for (const one of got.sessions ?? []) {
+        rows.push({ id: one.id, title: one.title, at: Number(one.createdAt) || 0 })
+      }
+    }
+    // 新的在前——和手机页展开一个工作区时的顺序同一条口径（那边也是按 createdAt 倒序）。
+    rows.sort((a, b) => b.at - a.at)
+    return {
+      rows: rows.slice(0, FEISHU_PICK_MAX).map((one) => ({ id: one.id, title: one.title })),
+      total,
+      bound: store.snapshot().boundSessionId ?? '',
+    }
+  }
+
+  /**
+   * 切到那一个会话。
+   *
+   * **切的是手机页同一个全局绑定**（和 `/mini/api/bind` 那条路逐条一样：bind → 读历史 →
+   * 广播一份快照），所以飞书里切完，手机页跟着变。这不是顺手：两边各绑各的会让用户
+   * 以为在跟同一个会话说话，而实际上没有。
+   */
+  function bindSessionForFeishu(sessionId) {
+    store.bind(sessionId)
+    // 和 /mini/api/bind 那条逐句一样：读这个会话的历史（异步补，读完自己会广播一份快照），
+    // 再广播一次当前快照——手机页正开着的话，它当场就跟着切过去了。
+    ensureHistory(sessionId)
+    server?.broadcast('state', store.snapshot())
+    return titleOfSession(sessionId)
+  }
+
+  /** 飞书那一块给设置页看的现状。**绝不包含 appSecret**，只回答「有没有凭据」。 */
+  function feishuStatus() {
+    const cfg = settings.feishu ?? {}
+    const live = feishu?.status?.() ?? null
+    return {
+      enabled: Boolean(cfg.enabled),
+      appId: String(cfg.appId ?? ''),
+      openIds: String(cfg.openIds ?? ''),
+      chatIds: String(cfg.chatIds ?? ''),
+      hasSecret: String(cfg.appSecret ?? '').trim() !== '',
+      starting: feishuStarting,
+      running: Boolean(feishu),
+      connected: Boolean(live?.connected),
+      // 上一次被白名单挡住的来源（含 open_id / chat_id 原值）。设置页要把这一行印出来：
+      // 名单默认是空的，用户不可能凭空知道自己的 id 长什么样，全靠这一行抄。
+      rejected: live?.rejected ?? null,
+      error: feishuError,
+    }
+  }
+
   // ------------------------------------------------------------------
   // 手机发来的指令 → 注入 DSH
   // ------------------------------------------------------------------
@@ -1105,6 +1327,21 @@ export function apply(ctx, config = {}) {
     // 状态必须是同一套口径，否则刷新一下就看到别人的结果了。
     if (sessionId !== targetSessionId()) return
 
+    if (action.kind === 'notice') {
+      // 子智能体完工的通知。记进聊天记录，**但不震动、不弹通知**——它是「你派出去的
+      // 那件事有结果了」，和「模型答了你一句」不是同一件事。可它确实是这个会话里
+      // 发生的一件事，聊天记录里不能缺（原来就是被 user/message 那道过滤一起挡掉的）。
+      store.pushNotice({
+        text: action.text,
+        summary: action.summary,
+        senderSessionId: action.senderSessionId,
+        sessionId,
+        timestamp: event.time,
+      })
+      server?.broadcast('state', store.snapshot())
+      return
+    }
+
     if (action.kind === 'user') {
       // 手机自己发的那条：onInstruction 里已经记过一笔了，这里跳过。
       // 不跳的话聊天模式里同一条指令会显示两次（用户实机报过）。
@@ -1141,6 +1378,10 @@ export function apply(ctx, config = {}) {
       timestamp: Date.now(),
     })
     maybeNotify(action.text)
+    // 飞书那条路：这一轮落定的回答，回给在飞书里发指令的那个人（见 onReply）。
+    // `sessionId` 既是**归属**（飞书那边靠它认出发起这一轮的那条消息），也要拿去查会话名；
+    // `userText` 是 events.js 取好的「这一轮用户的原话」，只做兜底比对。
+    onReply(action.text, { userText: action.userText, sessionId })
   })
 
   ctx.on('agent/status', ({ agent, status }) => {
@@ -1470,6 +1711,263 @@ export function apply(ctx, config = {}) {
     return null
   })
 
+  // ------------------------------------------------------------------
+  // 子智能体（2026-10-03 用户要求：把电脑端「子智能体」搬到手机）
+  //
+  // 和会话树同一套拿法：走 ctx.inject，服务不在就退回「没这个能力」。**不写进
+  // `inject` 数组**——写进去，headless 组合下这个服务永远不来，插件就整个不加载了
+  // （这个坑上面刚踩过，见 inject 那行的注释）。
+  //
+  // 三条路都**在进程内直接调 DSH 的服务**，不经过任何 HTTP / WebSocket：
+  //   `subagents`           子代理编排服务（列表、停止、继续）
+  //   `sessionProjections`  投影注册表（耗时、用量）
+  //   `sessions`            会话存储（不读日志就能拿到 Session 对象）
+  //
+  // 插件和它们同在一个进程里，这是它比桌面前端占便宜的地方：桌面前端只能隔着
+  // 一条 WebSocket 问，而那条线上只开了 `prompt` / `interruptByParent` 两个口子；
+  // 列表和运行记录它反而拿不到，得靠投影另推一份。
+  // ------------------------------------------------------------------
+  const subagentServices = { runtime: null, projections: null, sessions: null }
+  ctx.inject(['subagents'], (subCtx) => {
+    subagentServices.runtime = subCtx.subagents ?? null
+    // 和会话树那句同一个道理：配置里有不等于运行时真的提供了，这一句是唯一的事实来源。
+    console.log('[dsh-mini-remote] 子智能体服务已就绪：' + Boolean(subagentServices.runtime))
+  })
+  ctx.inject(['sessionProjections'], (projCtx) => {
+    subagentServices.projections = projCtx.sessionProjections ?? null
+  })
+  ctx.inject(['sessions'], (sessCtx) => {
+    subagentServices.sessions = sessCtx.sessions ?? null
+  })
+
+  /**
+   * DSH 那几个失败代号 → 一句人话。说不上来的照原样带出去，**不吞也不编**。
+   *
+   * 代号取自 dsh-subagent 的 `SubagentError.code`。头三句是手机上真点得到的三种：
+   * 父会话不在线、同时跑的数量满了、这道子智能体接不了话。
+   */
+  const SUBAGENT_FAILURES = {
+    PARENT_UNAVAILABLE: '它在的那个会话不在线了，这条发不过去。',
+    ACTIVATION_LIMIT_REACHED: '同时能跑的子智能体已经到上限了，等一个跑完再试。',
+    NOT_RESUMABLE: '这道子智能体没有对话可以接，只能看它跑过什么。',
+    UNAUTHORIZED: '这道子智能体不在当前会话名下。',
+    DRAINING: '它正在收尾，这会儿不接受新消息。',
+    ACTIVATION_CLOSING: '它正在停下，等停稳了再试。',
+    CONTINUATION_UNAVAILABLE: '这台电脑上的 DSH 没开「继续子智能体对话」这条路。',
+    PERSISTENCE_UNAVAILABLE: '这台电脑上的 DSH 没开会话记录，接不了话。',
+    CANCELLED: '这条请求已经取消了。',
+  }
+  function subagentFailure(err, what) {
+    const code = err?.code
+    if (typeof code === 'string' && SUBAGENT_FAILURES[code]) return SUBAGENT_FAILURES[code]
+    return `${what}：${err?.message ?? err}`
+  }
+
+  /**
+   * 每一行要的那两个数：耗时、用量。
+   *
+   * 都从 DSH 自己的投影里读（`subagentTiming` / `tokenUsage`），**不自己拿事件累加**——
+   * 自己算出来的数和电脑上那一栏对不上，用户一眼就看得出来。读不到就给 null，
+   * 页面上显示「—」：给 0 会被读成「真的一次都没跑过」，那是另一句话。
+   *
+   * 会话对象从 `sessions.get` 拿：内存里现成的，**不读日志**。老早跑完、进程里
+   * 已经不在的那些拿不到——那就如实空着，不为数字好看去读它整份日志。
+   */
+  function subagentMetrics(childId) {
+    const session = subagentServices.sessions?.get?.(childId)
+    const projections = subagentServices.projections
+    if (!session || typeof projections?.snapshot !== 'function') {
+      return { tokens: null, durationMs: null, lastTurnCompleted: null }
+    }
+    let values
+    try {
+      values = projections.snapshot(session, ['subagentTiming', 'tokenUsage'])?.values
+    } catch (err) {
+      return { tokens: null, durationMs: null, lastTurnCompleted: null }
+    }
+    let durationMs = null
+    // 「最近跑完的那一轮是正常收尾的」——页面上拿它区分绿点（真的干完了）和灰点（
+    // 没在跑，但不知道最后是怎么结束的）。读不到就给 null，别猜成「成功」。
+    let lastTurnCompleted = null
+    const timing = values?.subagentTiming
+    if (timing) {
+      // 跑完的轮次累加在 settledMs；还开着的那一轮按投影记的切面算，**不用 Date.now()**
+      // ——那会读出一个投影没盖到的时间，和电脑上对不上。
+      const settled = Number(timing.settledMs) || 0
+      const active = timing.active
+        ? Math.max(0, (Number(timing.active.through) || 0) - (Number(timing.active.since) || 0))
+        : 0
+      durationMs = settled + active
+      if (typeof timing.lastTurnCompleted === 'boolean') lastTurnCompleted = timing.lastTurnCompleted
+    }
+    let tokens = null
+    const usage = values?.tokenUsage
+    if (usage) {
+      // 四个桶互不重叠（dsh-token-meter 的注释：思考 token 已算在 output 里，不再加一次）。
+      tokens = (Number(usage.uncachedInputTokens) || 0) + (Number(usage.outputTokens) || 0)
+        + (Number(usage.cacheReadTokens) || 0) + (Number(usage.cacheWriteTokens) || 0)
+    }
+    return { tokens, durationMs, lastTurnCompleted }
+  }
+
+  /**
+   * 当前绑定会话派出的子智能体清单（含后代，按目录顺序）。
+   *
+   * `listDescendants` 读的是父会话自己的目录**事实**，不加载也不唤醒任何子代理——
+   * 所以列一下很便宜，也不会把睡着的子代理弄醒。
+   */
+  async function listSubagents(parentSessionId) {
+    const runtime = subagentServices.runtime
+    if (!parentSessionId) return { ok: false, error: '手机上还没有绑定会话。' }
+    if (typeof runtime?.listDescendants !== 'function') {
+      return { ok: false, error: '这台电脑上的 DSH 没提供子智能体。' }
+    }
+    let rows
+    try {
+      rows = await runtime.listDescendants(parentSessionId)
+    } catch (err) {
+      return { ok: false, error: subagentFailure(err, '读不到子智能体') }
+    }
+    const out = []
+    for (const row of rows ?? []) {
+      if (!row) continue
+      // 有一支目录读不动时，DSH 拿一行「诊断」顶上来（corrupt / unsupported / unavailable）。
+      // 如实转达，别当空的吞掉——吞了的表现是「明明有子智能体，却一个都不显示」。
+      if (row.kind === 'diagnostic') {
+        out.push({ id: String(row.id), diagnostic: String(row.reason ?? 'unavailable') })
+        continue
+      }
+      const metrics = subagentMetrics(row.id)
+      out.push({
+        id: String(row.id),
+        parentId: String(row.parentId ?? ''),
+        depth: Number(row.depth) || 1,
+        // 只有「可续接」谈得上继续聊；两个值之外的都按一次性处理——未知模式不许接话。
+        mode: row.mode === 'continuable' ? 'continuable' : 'one-shot',
+        label: typeof row.label === 'string' ? row.label : '',
+        running: row.activity === 'running',
+        tokens: metrics.tokens,
+        durationMs: metrics.durationMs,
+        lastTurnCompleted: metrics.lastTurnCompleted,
+      })
+    }
+    return { ok: true, subagents: out, boundSessionId: parentSessionId }
+  }
+
+  /**
+   * 某个子智能体**自己的运行过程**。
+   *
+   * 数据来源和主会话**完全同一条**：`sessionQuery.readSession(childId)` 拿原始事件，
+   * `replayHistory` 重放成聊天记录（和实时那条路共用同一个提取器）。电脑端「点进去
+   * 看它跑了什么」看的也是它自己的会话记录，两边因此长得一样——各写一套迟早会走散。
+   *
+   * 地址是手机传上来的，**不能拿它当权限**：先确认它真的挂在当前绑定会话名下。
+   */
+  async function subagentTranscript(childId, parentSessionId) {
+    if (!childId) return { ok: false, error: '没说要读哪一道子智能体。' }
+    const listed = await listSubagents(parentSessionId)
+    if (!listed.ok) return listed
+    const row = listed.subagents.find((s) => s.id === childId)
+    if (!row) return { ok: false, error: '这道子智能体不在当前会话名下。' }
+    const q = treeServices.query
+    if (typeof q?.readSession !== 'function') {
+      return { ok: false, error: '这台电脑上的 DSH 没提供读取会话记录的能力。' }
+    }
+    let snap
+    try {
+      snap = await q.readSession(childId)
+    } catch (err) {
+      return { ok: false, error: subagentFailure(err, '读不到它的记录') }
+    }
+    const events = Array.isArray(snap?.events) ? snap.events : []
+    if (!events.length) {
+      // 一次性子智能体跑完、记录已被回收时就是这里。**如实说没有记录**，不拿
+      // 「读不到」冒充「它没干过活」——这两件事对用户含义不同。
+      return {
+        ok: true, mode: row.mode, running: row.running,
+        entries: [], reclaimed: true, truncated: false, note: null,
+      }
+    }
+    const capped = capEntries(replayHistory(events))
+    return {
+      ok: true,
+      mode: row.mode,
+      running: row.running,
+      entries: capped.entries,
+      reclaimed: false,
+      truncated: capped.dropped > 0,
+      note: capped.dropped > 0 ? `只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条）` : null,
+    }
+  }
+
+  /**
+   * 停：只停**当前这一轮**，不销毁这道子智能体（排队里的消息、它的后代都留着）。
+   *
+   * 权限走「人」这条：`interruptByParent(childId, parentSessionId, mode)` 拿这三个当凭据，
+   * 它**不做父 Agent 在线检查**——这正是「父会话不在线，也能停下正在跑的它」的原因。
+   * 一次性的没有可停的轮次，这里就挡掉，不往 DSH 递。
+   */
+  async function stopSubagent(childId, parentSessionId, mode) {
+    const runtime = subagentServices.runtime
+    if (!childId) return { ok: false, error: '没说要停哪一道子智能体。' }
+    if (!parentSessionId) return { ok: false, error: '手机上还没有绑定会话。' }
+    if (mode !== 'continuable') {
+      return { ok: false, error: '这是一次性子智能体，跑完就结束，没有可停的轮次。' }
+    }
+    if (typeof runtime?.interruptByParent !== 'function') {
+      return { ok: false, error: '这台电脑上的 DSH 没提供停止子智能体的能力。' }
+    }
+    try {
+      await runtime.interruptByParent(childId, parentSessionId, 'continuable')
+    } catch (err) {
+      return { ok: false, error: subagentFailure(err, '停不下来') }
+    }
+    // 和主会话那条同一个口径：递进去不等于停稳，界面上得等它的状态翻过来。
+    return { ok: true }
+  }
+
+  /**
+   * 继续：往这道子智能体里递一句**人**的话。
+   *
+   * `prompt` 把这条记成 `source.kind === 'user'`（带 rpcId），也就是「你在它旁边说了
+   * 一句」，而不是「别的 agent 转达的」。delivery 选 queue（排到它当前这轮之后）——
+   * 和手机自己对主会话的做法一致：主会话正在跑时，手机上发的指令也是排队，不打断。
+   *
+   * requestId 是这条消息的身份，**每次都得新铸一个**：复用同一个会被判成重复投递。
+   */
+  async function askSubagent(childId, parentSessionId, mode, text) {
+    const runtime = subagentServices.runtime
+    if (!childId) return { ok: false, error: '没说要跟哪一道子智能体说话。' }
+    if (!parentSessionId) return { ok: false, error: '手机上还没有绑定会话。' }
+    if (!text) return { ok: false, error: '话是空的。' }
+    if (mode !== 'continuable') {
+      return { ok: false, error: '这是一次性子智能体，跑完就结束了，接不了话。' }
+    }
+    if (typeof runtime?.prompt !== 'function') {
+      return { ok: false, error: '这台电脑上的 DSH 没提供继续子智能体对话的能力。' }
+    }
+    let requestId
+    try {
+      requestId = randomUUID()
+    } catch (err) {
+      // 兜底：uuid 拿不到也不该让这句话发不出去。
+      requestId = 'mini-' + Date.now() + '-' + randomBytes(8).toString('hex')
+    }
+    try {
+      const receipt = await runtime.prompt({
+        requestId,
+        parentSessionId,
+        childSessionId: childId,
+        mode: 'continuable',
+        delivery: 'queue',
+        content: [{ type: 'text', text }],
+      })
+      return { ok: true, messageId: receipt?.messageId ? String(receipt.messageId) : null }
+    } catch (err) {
+      return { ok: false, error: subagentFailure(err, '这句话没送出去') }
+    }
+  }
+
   // ------------------------------------------------------------------
   // 手机上答题：把电脑这边的提问推到手机，等它答，再把答案交还给电脑。
   //
@@ -1507,6 +2005,23 @@ export function apply(ctx, config = {}) {
     // 能力从 `miniControl` 这个固定取用点拿（服务启动时主动放进去的），
     // **不再经过 createMiniServer 的回执**——实测那个回执兑现出来是 undefined。
     const phoneReady = typeof miniControl.hasPhone === 'function' ? miniControl.hasPhone() : false
+    /**
+     * **飞书那条路此刻能不能接这道题。**
+     *
+     * 三个条件，缺一不接：
+     *   ① 通路在、而且**有一轮从飞书发起的指令还没落定**（见 lib/lark.js 的 serving）——
+     *      手机上发起的轮次不该因此抢掉电脑上的弹窗；
+     *   ② 这道题在飞书里写得成一段纯文本（`feishuQuestionText` 写不成时给空串：
+     *      两道以上的题里混着一道没有选项的题，数字协议表达不了）；
+     *   ③ 那段话不超过一条消息的上限。
+     * 接不了就当飞书那边不存在，电脑和手机照旧——**一个字都不变**。
+     */
+    const askText = feishuQuestionText(questions)
+    const feishuReady = Boolean(feishu)
+      && askText !== ''
+      && askText.length <= FEISHU_TEXT_LIMIT
+      && typeof feishu.serving === 'function'
+      && feishu.serving()
     /**
      * **让路的那三种情况，每一种都留一行。**
      *
@@ -1520,8 +2035,8 @@ export function apply(ctx, config = {}) {
       console.log(`[dsh-mini-remote] 提问让路：问的=${agentId ?? '无'}，手机绑的=${bound ?? '无'}，题目数=${questions.length}`)
       return next()
     }
-    if (!phoneReady) {
-      console.log('[dsh-mini-remote] 提问让路：手机上此刻没有连接（页面没开、锁屏或断网），交给电脑')
+    if (!phoneReady && !feishuReady) {
+      console.log('[dsh-mini-remote] 提问让路：手机和飞书此刻都接不上（页面没开、锁屏或断网，飞书那头没有在等的轮次），交给电脑')
       return next()
     }
     if (typeof miniControl.askPhone !== 'function') {
@@ -1529,11 +2044,28 @@ export function apply(ctx, config = {}) {
       return next()
     }
     // ——— 同步交出"将来会有答案"的东西；下面的等待都在这里，不再有同步判断 ———
-    console.log(`[dsh-mini-remote] 提问推给手机：${questions.length} 题，等它答`)
-    return miniControl.askPhone(questions, agentId).then((answer) => {
+    console.log(`[dsh-mini-remote] 提问推给手机：${questions.length} 题，等它答`
+      + (feishuReady ? '（飞书那边一起问）' : ''))
+    /**
+     * `askId` 是这道题在**手机页那份清单**里的编号，由 `onPending` 当场交出来。
+     * 它只用来问一件事：「飞书那边还挂着这道题吗」（见 keepAlive）——
+     * 题目的胜负、谁先答谁生效，全在 lib/server.js 那份清单里，这里不另判。
+     */
+    let askId = null
+    return miniControl.askPhone(questions, agentId, {
+      onPending: (id) => {
+        askId = id
+        // 飞书那边写成一段普通文字问出来。它没接（写不成、或发不出去就当场撤回）时，
+        // keepAlive 下一次为 false，题照旧还给电脑。
+        feishu?.openAsk?.({ id, kind: 'question', payload: questions })
+      },
+      // 「手机全断了要不要收摊」的第二个判据：飞书那边还挂着这道题就别收。
+      keepAlive: () => Boolean(feishu && askId && feishu.isWaiting?.(askId)),
+    }).then((answer) => {
       // 手机中途没了：把问题还给电脑，那边照常弹窗——不会两头都答不上。
       // 这一句日志是「手机上答了、电脑上没动静」那类现象唯一能落下来的痕迹：
       // 有它才知道手机那份答案没接上（断线、或者答晚了一步），而不是插件没在跑。
+      if (askId) feishu?.expireAsk?.(askId)
       if (!answer) {
         console.log('[dsh-mini-remote] 手机上没答成（连接断了、或者答晚了），这题还给电脑')
         return next()
@@ -1542,6 +2074,7 @@ export function apply(ctx, config = {}) {
       return answer
     }).catch((err) => {
       // 我这边出任何问题都不能把提问吞掉，一律让回电脑。
+      if (askId) feishu?.expireAsk?.(askId)
       console.log('[dsh-mini-remote] 接管提问出错，让回电脑：' + String(err))
       return next()
     })
@@ -1562,20 +2095,40 @@ export function apply(ctx, config = {}) {
     // 这次到底要跑什么：审批请求只带调用编号，参数在会话事件里记着的那份。
     const command = request?.callId ? (toolCalls.get(String(request.callId)) ?? '') : ''
     const phoneReady = typeof miniControl.hasPhone === 'function' ? miniControl.hasPhone() : false
+    // 飞书那条路此刻能不能接：判据和上面那条提问链**一模一样**（可能接、写得成、不超长）。
+    const view = {
+      toolName: typeof toolName === 'string' && toolName ? toolName : '某个工具',
+      reason: typeof request?.reason === 'string' ? request.reason : '',
+      command: typeof command === 'string' ? command : '',
+    }
+    const approvalAskText = approvalText(view)
+    const feishuReady = Boolean(feishu)
+      && approvalAskText.length <= FEISHU_TEXT_LIMIT
+      && typeof feishu.serving === 'function'
+      && feishu.serving()
     if (!agentId || agentId !== bound) {
       console.log(`[dsh-mini-remote] 审批让路：批的=${agentId ?? '无'}，手机绑的=${bound ?? '无'}`)
       return next()
     }
-    if (!phoneReady) {
-      console.log('[dsh-mini-remote] 审批让路：手机上此刻没有连接（页面没开、锁屏或断网），交给电脑')
+    if (!phoneReady && !feishuReady) {
+      console.log('[dsh-mini-remote] 审批让路：手机和飞书此刻都接不上（页面没开、锁屏或断网，飞书那头没有在等的轮次），交给电脑')
       return next()
     }
     if (typeof miniControl.askApproval !== 'function') {
       console.log('[dsh-mini-remote] 审批让路：拿不到 askApproval（手机服务还没起来），交给电脑')
       return next()
     }
-    console.log(`[dsh-mini-remote] 审批推给手机：${toolName}，等它拍板`)
-    return miniControl.askApproval(request, agentId, command).then((outcome) => {
+    console.log(`[dsh-mini-remote] 审批推给手机：${toolName}，等它拍板`
+      + (feishuReady ? '（飞书那边一起问）' : ''))
+    let askId = null
+    return miniControl.askApproval(request, agentId, command, {
+      onPending: (id) => {
+        askId = id
+        feishu?.openAsk?.({ id, kind: 'approval', payload: view })
+      },
+      keepAlive: () => Boolean(feishu && askId && feishu.isWaiting?.(askId)),
+    }).then((outcome) => {
+      if (askId) feishu?.expireAsk?.(askId)
       if (!outcome) {
         console.log('[dsh-mini-remote] 手机上没拍成（连接断了、或者拍晚了），这条还给电脑')
         return next()
@@ -1583,6 +2136,7 @@ export function apply(ctx, config = {}) {
       console.log('[dsh-mini-remote] 手机上拍板了：' + outcome)
       return outcome
     }).catch((err) => {
+      if (askId) feishu?.expireAsk?.(askId)
       console.log('[dsh-mini-remote] 接管审批出错，让回电脑：' + String(err))
       return next()
     })
@@ -1782,7 +2336,7 @@ export function apply(ctx, config = {}) {
   const nav = {
     listWorkspaces: (runningIds, force, includeEmpty) =>
       listWorkspaces({ registry: treeServices.registry, query: treeServices.query, runningIds, force, includeEmpty }),
-    listSessionsOf: (workspaceId, limit, force) =>
+    listSessionsOf: (workspaceId, limit, force, onTitle) =>
       listSessionsOf({
         registry: treeServices.registry,
         query: treeServices.query,
@@ -1792,6 +2346,7 @@ export function apply(ctx, config = {}) {
         workspaceId,
         limit,
         force,
+        onTitle,
       }),
     // 建会话：先用 inject 拿到的那个，拿不到就现读一次——`ctx.get` 对没写进 inject
     // 的服务名是**返回 undefined**（不是抛错），所以这么写是安全的。
@@ -1817,6 +2372,13 @@ export function apply(ctx, config = {}) {
     setPermission: (sessionId, name) =>
       setPreset({ service: presets.service, session: sessionFor(sessionId), name }),
 
+    // 子智能体（2026-10-03）。四条都取**当前绑定会话**那一份，和上面 send / stop
+    // 同一套口径：手机上遥控的是你正看着的那个会话，不该牵动你在电脑上另开的那个。
+    subagents: (sessionId) => listSubagents(sessionId),
+    subagentTranscript: (childId, sessionId) => subagentTranscript(childId, sessionId),
+    stopSubagent: (childId, sessionId, mode) => stopSubagent(childId, sessionId, mode),
+    askSubagent: (childId, sessionId, mode, text) => askSubagent(childId, sessionId, mode, text),
+
     // 模型与思考强度（2026-09-25 用户要求：手机上要能改每个会话的模型和强度）。
     // `canCreate.controller` 就是 `ctx.sessionController`——和上面 createSession 同一个东西。
     //
@@ -1982,6 +2544,12 @@ export function apply(ctx, config = {}) {
       // 手机点开会话（或刷新页面）时，把那条会话的完整历史读出来。
       onSessionOpened: (sessionId) => ensureHistory(sessionId),
       tree: nav,
+      // 正文里写相对路径的图（`![](scratch/a.png)`）相对的是**那段对话的工作目录**，
+      // 而不一定是插件根。所以把当前已注册工作区的目录一并递过去当额外候选根。
+      // `treeServices.registry` 就是 DSH 的 workspaceRegistry（注入见上面那段），
+      // 服务这边拿不到 ctx，只能由插件给——传函数不传快照，理由和 treeServices 一样：
+      // 服务每次请求现读，工作区是随时会变的。
+      imageRoots: () => (treeServices.registry?.list?.() ?? []).map((w) => w?.path),
       // 目录浏览自己读盘（理由见 lib/browse.js 开头：DSH 的目录选择器在
       // 「Windows + 只绑回环」时会判成 native，那套动词是直接拒绝的，
       // 会在电脑屏幕上弹框——而用户正在外面用手机）。
@@ -2030,6 +2598,29 @@ export function apply(ctx, config = {}) {
     }
   })
 
+  // ------------------------------------------------------------------
+  // 飞书那条路自己的生死
+  // ------------------------------------------------------------------
+  /**
+   * 单独一个 effect，不和手机服务那一个搅在一起：这两样各有各的失败方式，
+   * 一个起不来不该把另一个拖下水。
+   *
+   * `closed` 那一道和手机服务同一个道理——建连接是异步的，而插件随时可能被卸载。
+   * 建好时如果已经卸了，当场把它关掉，不能留下一条没人管的连接和它自己的定时器。
+   */
+  ctx.effect(() => {
+    let closed = false
+    const start = async () => {
+      await bringFeishuUp()
+      if (closed) bringFeishuDown()
+    }
+    start()
+    return () => {
+      closed = true
+      bringFeishuDown()
+    }
+  })
+
   // ------------------------------------------------------------------
   // DSH 设置页的「手机遥控」标签从这里取数据
   // ------------------------------------------------------------------
@@ -2069,6 +2660,9 @@ export function apply(ctx, config = {}) {
             error: serverError
               ? `手机服务起不来：${serverError}\n端口可以在设置文件里改（settings.json 里的 port）。`
               : '手机服务还在启动，过几秒刷新一下。',
+            // 手机服务没起来，不影响飞书那一块——它和手机服务没有关系，谁用谁的。
+            // 所以这一条早退路径上也带着 feishu，用户至少改得动它。
+            feishu: feishuStatus(),
           },
         }
       }
@@ -2096,6 +2690,8 @@ export function apply(ctx, config = {}) {
          * 端口被占时服务会自己往后让，用配置值会指错。
          */
         serve: await serveState(server.port),
+        // 飞书那一块的现状（**永远不含 appSecret**，只回答「有没有凭据」）。
+        feishu: feishuStatus(),
       })
       return { status: payload.ok ? 200 : 500, body: payload }
     }
@@ -2264,6 +2860,57 @@ export function apply(ctx, config = {}) {
       },
     })
 
+    /**
+     * 飞书那一块的配置：开关、两个凭据、两个允许名单。
+     *
+     * 和公网开关、改密码一样**只允许本机调用**：那是一对凭据，改它等于改这个插件
+     * 在飞书那边的身份。同一个 Wi-Fi 下的别人不该替你做主。
+     *
+     * 两条不成文但必须守的规矩：
+     *   1. **appSecret 从不回显**（见 feishuStatus）。所以界面上那个框天生是空的，
+     *      于是「留空」只能解释成「不改动原来那份」——不然用户每点一次保存都得重新
+     *      贴一遍密码，贴错一次就是一段查不出原因的鉴权失败。
+     *   2. 存完**就地重建连接**。飞书的长连接是绑在凭据上的，不重建的话用户会看到
+     *      「填好了、开关也开着，就是不回消息」，而屏幕上没有任何东西提示他原因。
+     */
+    const offFeishu = webServer.register({
+      kind: 'exact',
+      path: '/mini-remote/feishu',
+      handler: async (req, res) => {
+        if (!localOnly(req, res)) return
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { ok: false, error: '这个地址只接受 POST。' })
+          return
+        }
+        let want
+        try {
+          want = await readBody(req)
+        } catch (err) {
+          sendJson(res, 400, { ok: false, error: `请求体读不了：${err?.message ?? err}` })
+          return
+        }
+        const next = {
+          enabled: Boolean(want?.enabled),
+          appId: typeof want?.appId === 'string' ? want.appId.trim() : '',
+          appSecret: typeof want?.appSecret === 'string' ? want.appSecret.trim() : '',
+          openIds: typeof want?.openIds === 'string' ? want.openIds.trim() : '',
+          chatIds: typeof want?.chatIds === 'string' ? want.chatIds.trim() : '',
+        }
+        // 留空 = 保留原来那份（理由见上面第 1 条）。
+        if (!next.appSecret) next.appSecret = String(settings.feishu?.appSecret ?? '')
+        settings.feishu = next
+        persistSettings()
+        if (next.enabled) await restartFeishu()
+        else bringFeishuDown()
+        try {
+          const { status, body } = await pairingPayload()
+          sendJson(res, status, body)
+        } catch (err) {
+          sendJson(res, 500, { ok: false, error: `改完之后读不到状态：${err?.message ?? err}` })
+        }
+      },
+    })
+
     /**
      * 卸载时把注册过的路由全部注销。
      *
@@ -2271,13 +2918,14 @@ export function apply(ctx, config = {}) {
      * 还挂在服务器上，指向一个已经死掉的闭包——再有人打过来就是莫名其妙的报错。
      *
      * 2026-09-24 补：`offToken` 一直是漏的（改密码那条路由注册了却没注销），
-     * 加 HTTPS 这条时对照着数了一遍才发现。四条注册，四条注销，现在对得上。
+     * 加 HTTPS 这条时对照着数了一遍才发现。五条注册，五条注销，现在对得上。
      */
     return () => {
       offGet?.()
       offTunnel?.()
       offServe?.()
       offToken?.()
+      offFeishu?.()
     }
   })
 }