@yolk_vat-y/dsh-project-memory 0.5.6 → 0.5.8

package/src/chunker.js

@@ -20,17 +20,25 @@ export function chunkText(text, chunkChars = 3000, maxChunks = 40) {
 
   const chunks = []
   for (const section of sections) {
-    if (!section.lines.join('').trim()) continue
-    let block = section.lines.join('\n').trim()
-    let line = section.line
+    const rawBlock = section.lines.join('\n')
+    if (!rawBlock.trim()) continue
+    // `.trim()` 会吃掉段首的空白与换行——把它们算进行号，否则整段的引用行号会偏低。
+    const lead = rawBlock.match(/^\s*/)[0]
+    let line = section.line + (lead.match(/\n/g) || []).length
+    let block = rawBlock.trim()
     while (block.length > chunkChars) {
       let splitAt = block.lastIndexOf('\n\n', chunkChars)
       if (splitAt < chunkChars * 0.5) splitAt = block.lastIndexOf(' ', chunkChars)
       if (splitAt < chunkChars * 0.5) splitAt = chunkChars
-      const part = block.slice(0, splitAt).trim()
+      const rawPart = block.slice(0, splitAt)
+      const part = rawPart.trim()
       if (part) chunks.push({ title: section.title, text: part, line })
-      line += part.split('\n').length
-      block = block.slice(splitAt).trim()
+      // 行号按**原始**切片里的换行数推进，再加上被下一次 trim 吃掉的段首换行。
+      // 旧写法 `part.split('\n').length` 每次跨行切分都要多算一行，误差会累积。
+      const rest = block.slice(splitAt)
+      const nextLead = rest.match(/^\s*/)[0]
+      line += (rawPart.match(/\n/g) || []).length + (nextLead.match(/\n/g) || []).length
+      block = rest.trim()
       if (chunks.length >= maxChunks) break
     }
     if (block) {

package/src/client/MemoryView.tsx

@@ -120,6 +120,14 @@ export function MemoryView({
   const lastRunRef = useRef(0)
 
   const refresh = useCallback(async (force = false): Promise<void> => {
+    // 没有活跃会话时不发命令、也不报错：面板顶部已经显示「还没有会话」，
+    // 再报一次"同步失败"会让人以为记忆库坏了（0.1.7 上会话快照结构变化时就是这个表象）。
+    if (!sessionId) {
+      setPayload(null)
+      setError(null)
+      setLoading(false)
+      return
+    }
     if (inflightRef.current) return
     const now = Date.now()
     if (!force && now - lastRunRef.current < 800) return
@@ -128,7 +136,7 @@ export function MemoryView({
     setLoading(true)
     setError(null)
     try {
-      const res = await runLine(`/insight list ${scope}`)
+      const res = await runLine(`/tasks insight list ${scope}`)
       if (!res.ok) {
         setError(res.text)
         setPayload(null)
@@ -152,7 +160,7 @@ export function MemoryView({
     setBusy(true)
     setError(null)
     try {
-      const line = `/insight ${action} ${scope} ${id}${action === 'demote' && scope === 'project' && boundTaskId ? ` ${boundTaskId}` : ''}`
+      const line = `/tasks insight ${action} ${scope} ${id}${action === 'demote' && scope === 'project' && boundTaskId ? ` ${boundTaskId}` : ''}`
       const res = await runLine(line)
       if (!res.ok) setError(res.text)
       else void refresh(true)
@@ -230,8 +238,8 @@ export function MemoryView({
         fields.trigger = { keywords: form.trigger.split(/[,，]/).map((s) => s.trim()).filter(Boolean) }
       }
       const line = editingId
-        ? `/insight edit ${scope} ${editingId} ${JSON.stringify(fields)}`
-        : `/insight save ${scope} ${JSON.stringify(fields)}`
+        ? `/tasks insight edit ${scope} ${editingId} ${JSON.stringify(fields)}`
+        : `/tasks insight save ${scope} ${JSON.stringify(fields)}`
       const res = await runLine(line)
       if (!res.ok) {
         setError(res.text)

package/src/client/TaskCommandNode.tsx

@@ -4,7 +4,7 @@
  * 目的：大 JSON 载荷绝不整段渲染进对话（否则切视图会刷屏）。
  */
 import { useEffect, useRef } from 'react'
-import { IconFolderOpenOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconFolderOpenOutline16 } from './icons.ts'
 import { parseTaskPayloadText, taskDataStore } from './task-data-store.ts'
 import { parseInsightPayloadText } from './MemoryView.tsx'
 import { taskUIStore } from './task-ui-store.ts'

package/src/client/TaskComponents.tsx

@@ -3,14 +3,15 @@
  * 纯渲染 + 卡片局部行内编辑/拖拽状态，动作经 props 回调交给容器（TaskPanel.tsx）。
  */
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+// 图标走兼容层：0.1.5 用 IconXxx14/16，0.1.7+ 改成 IconXxxRegular + size prop
 import {
-  Button,
   IconChevronDownOutline14,
   IconChevronUpOutline14,
   IconCheckOutline16,
   IconPlayOutline16,
   IconFolderOpenOutline16,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+} from './icons.ts'
 import { createTranslate } from './locales.ts'
 import { useTaskDrag } from './task-hooks.ts'
 import { type Task, type TaskInsight, type TaskStep } from './task-data-store.ts'

package/src/client/TaskPanel.tsx

@@ -4,18 +4,20 @@
  * Presentational 组件在 TaskComponents.tsx
  */
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
+import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
+// 图标走兼容层：0.1.5 用 IconXxx14/16，0.1.7+ 改成 IconXxxRegular + size prop
 import {
-  Button,
   IconChevronDownOutline14,
   IconCloseOutline16,
   IconFolderOpenOutline16,
   IconQuestionOutline14,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+} from './icons.ts'
 import { createTranslate, zh, en } from './locales.ts'
 import { useTaskData, useTaskDataActions, taskDataStore, parseTaskPayloadText, type TaskStep } from './task-data-store.ts'
 import { useTaskUI, useTaskUIActions } from './task-ui-store.ts'
 import { MiniBar, TaskCard } from './TaskComponents.tsx'
 import { MemoryView, type InsightScope } from './MemoryView.tsx'
+import { pickSessionId } from './session-id.js'
 import css from './TaskPanel.module.css'
 
 const NS = 'dsh-project-memory'
@@ -36,11 +38,9 @@ function useSessionId(ctx: any): string | null {
     if (!list || typeof list.subscribe !== 'function') return
     return list.subscribe(() => force((n) => n + 1))
   }, [ctx])
-  const snap = ctx?.sessions?.list?.getSnapshot?.()
-  if (!snap) return null
-  if (snap.current) return snap.current
-  const first = Array.isArray(snap.items) ? snap.items.find((s: any) => !s.blank) ?? snap.items[0] : undefined
-  return first?.sessionId ?? null
+  // 快照结构在 dsh 0.1.7 变过（current/items → ids/byId）：解析与兼容都在 session-id.js，
+  // 那里有单测；这里只负责订阅与取值。
+  return pickSessionId(ctx?.sessions?.list?.getSnapshot?.())
 }
 
 class PanelErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
@@ -134,7 +134,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
       await runLine('/tasks')
       const newBoundId = taskDataStore.getSnapshot().boundTaskId
       if (newBoundId && newBoundId !== prevBoundId) {
-        await runLine(`/task switch ${newBoundId}`)
+        await runLine(`/tasks switch ${newBoundId}`)
       }
     } finally {
       setSyncing(false)
@@ -145,7 +145,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
     if (syncing) return
     setSyncing(true)
     try {
-      await runLine(`/task ${verb} ${taskId}`)
+      await runLine(`/tasks ${verb} ${taskId}`)
     } finally {
       setSyncing(false)
     }
@@ -156,7 +156,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
     if (syncing) return
     setSyncing(true)
     try {
-      await runLine(`/insight ${action} task ${id}`)
+      await runLine(`/tasks insight ${action} task ${id}`)
       await refresh()
     } finally {
       setSyncing(false)
@@ -164,7 +164,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
   }
 
   const pushSteps = (taskId: string, steps: TaskStep[]): void => {
-    void runLine(`/task todos ${JSON.stringify(steps.map((s) => ({ content: s.content, status: s.status })))}`)
+    void runLine(`/tasks todos ${JSON.stringify(steps.map((s) => ({ content: s.content, status: s.status })))}`)
   }
 
   const cycleStatus = (taskId: string, index: number) => {
@@ -206,7 +206,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
     if (!task) return
     const same = task.title === trimmed
     if (same || !trimmed) return
-    void runLine(`/task rename ${taskId} ${JSON.stringify(trimmed)}`)
+    void runLine(`/tasks rename ${taskId} ${JSON.stringify(trimmed)}`)
   }
 
   const expand = () => {
@@ -421,7 +421,7 @@ function TaskPanelView({ ctx }: { ctx: any }) {
                 expanded={expanded}
                 onToggleExpand={() => uiActions.toggleTaskExpanded(task.id)}
                 onSwitch={() => handleAction('switch', task.id)}
-                onUnbind={() => runLine('/task unbind')}
+                onUnbind={() => runLine('/tasks unbind')}
                 onArchive={() => handleAction('archive', task.id)}
                 onRename={(value) => commitTitle(task.id, value)}
                 onEditStep={(index, value) => commitStepText(task.id, index, value)}

package/src/client/client.ts

@@ -10,10 +10,14 @@
  *
  * 只依赖宿主 seed 提供的模块（react / dsh-client-ui-primitives），
  * 数据经 remote.commands.execute 执行 /tasks 命令获取 JSON 快照。
+ *
+ * 另有一个可选增强：自建的 `/` 菜单源（slash.ts），把三条命令收进一个带图标和
+ * 小节标题的「工作流」组。它**整体是可选的**——宿主没有 slash 触发器服务时静默跳过。
  */
 import { createElement } from 'react'
 import { TaskPanelEntry } from './TaskPanel.tsx'
 import { TaskCommandNode } from './TaskCommandNode.tsx'
+import { createSlashSource } from './slash.ts'
 
 const NS = 'dsh-project-memory'
 
@@ -22,32 +26,100 @@ export const name = NS
 /** Required client services: slots registry, session scopes, commands remote (data 通道). */
 export const inject = ['slots', 'sessions', 'remote', 'remote.commands', 'locale']
 
+/**
+ * 执行一条命令行，映射成 composer 的 SubmitOutcome。
+ * 与 TaskPanel 走同一个 remote.commands.execute 通道（同样的返回信封）。
+ * @param commands - ctx.remote.commands
+ * @param session - 会话投影（只读 sessionId）
+ * @param line - 完整命令行（含前导斜杠）
+ * @param attachments - 提交附件（菜单路径恒为空）
+ * @returns {kind:'success'|'error', text?}
+ */
+async function runCommand(
+  commands: any,
+  session: any,
+  line: string,
+  attachments: readonly unknown[] = [],
+): Promise<{ kind: 'success' | 'error'; text?: string }> {
+  const sessionId = session?.sessionId
+  if (typeof sessionId !== 'string' || !commands || typeof commands.execute !== 'function') {
+    return { kind: 'error', text: `no session / commands service for ${line}` }
+  }
+  const response: any = await commands.execute(sessionId, line, [...attachments])
+  const envelope = response as { ok?: boolean; error?: any; value?: any } | null | undefined
+  if (envelope && typeof envelope === 'object' && envelope.ok === false) {
+    return { kind: 'error', text: `command.execute failed: ${envelope.error?.code ?? 'unknown'}` }
+  }
+  const execution = envelope && typeof envelope === 'object' && 'value' in envelope ? envelope.value : envelope
+  const result = execution?.result ?? execution
+  if (result?.kind === 'error') return { kind: 'error', text: result.text ?? `${line} failed` }
+  return { kind: 'success' }
+}
+
+/**
+ * 注册自建的 `/` 菜单源（见 slash.ts）。
+ *
+ * 整段都是**可选增强**：宿主没有 `inputTriggers` 服务、或该服务换了契约时，绝不能因此
+ * 让整个 client 插件挂掉——那会连任务面板一起消失。`inputTriggers` 因此不进顶层 `inject`
+ * （顶层 inject 未满足时 cordis 根本不会调用 apply），而是走嵌套 inject + 两层 try/catch。
+ * @param ctx - client 根上下文
+ */
+function registerSlashSource(ctx: any): void {
+  if (typeof ctx?.inject !== 'function') {
+    console.warn(`[${NS}] host has no ctx.inject — slash menu group disabled`)
+    return
+  }
+  try {
+    ctx.inject(['inputTriggers', 'sessions', 'remote.commands'], (scope: any) => {
+      try {
+        const inputTriggers = scope?.inputTriggers
+        if (!inputTriggers || typeof inputTriggers.registerSource !== 'function') {
+          console.warn(`[${NS}] host has no inputTriggers.registerSource — slash menu group disabled`)
+          return
+        }
+        const source = createSlashSource(scope, {
+          sessions: scope.sessions,
+          run: (session, line, attachments) => runCommand(scope?.remote?.commands, session, line, attachments),
+        })
+        scope.effect(() => inputTriggers.registerSource(source), 'dsh-project-memory: slash source')
+      } catch (err) {
+        console.warn(`[${NS}] slash source registration failed:`, err)
+      }
+    })
+  } catch (err) {
+    console.warn(`[${NS}] slash source injection failed:`, err)
+  }
+}
+
 export function apply(ctx: any): void {
   const slots = ctx?.slots
   if (!slots || typeof slots.inject !== 'function') {
     console.warn(`[${NS}] host has no slots service — task panel disabled`)
-    return
-  }
-  try {
-    slots.inject('shell.overlay', () => slots.register(
-      {
-        name: 'shell.overlay',
-        id: 'dsh-project-memory-task-panel',
-        order: 100, // 浮层顺序：低于 toast/弹窗即可，越高越靠后渲染
-      },
-      () => createElement(TaskPanelEntry, { ctx })
-    ))
-
-    // 会话内 /tasks、/task、/insight 命令节点：按命令名 key 接管渲染，
-    // 替换内置大段文本卡片（文本含 JSON 载荷，只有面板需要它），避免载荷刷屏对话。
-    const nodeKeys = ['tasks', 'task', 'insight']
-    for (const key of nodeKeys) {
-      slots.inject('conversation.chat.commandview', () => slots.register(
-        { name: 'conversation.chat.commandview', key },
-        TaskCommandNode
+  } else {
+    try {
+      slots.inject('shell.overlay', () => slots.register(
+        {
+          name: 'shell.overlay',
+          id: 'dsh-project-memory-task-panel',
+          order: 100, // 浮层顺序：低于 toast/弹窗即可，越高越靠后渲染
+        },
+        () => createElement(TaskPanelEntry, { ctx })
       ))
+
+      // 会话内命令节点：按命令名 key 接管渲染，替换内置大段文本卡片
+      // （文本含 JSON 载荷，只有面板需要它），避免载荷刷屏对话。
+      // 合并后只剩一条用户命令 /tasks（子动词都记在同一个命令名下）。
+      const nodeKeys = ['tasks']
+      for (const key of nodeKeys) {
+        slots.inject('conversation.chat.commandview', () => slots.register(
+          { name: 'conversation.chat.commandview', key },
+          TaskCommandNode
+        ))
+      }
+    } catch (err) {
+      console.warn(`[${NS}] task panel registration failed:`, err)
     }
-  } catch (err) {
-    console.warn(`[${NS}] task panel registration failed:`, err)
   }
+
+  registerSlashSource(ctx)
 }

package/src/client/icons.ts

@@ -0,0 +1,63 @@
+/**
+ * 宿主图标兼容层（dsh 0.1.5 ↔ 0.1.7+）。
+ *
+ * 命名契约变过一次：
+ *   - dsh 0.1.5（含 0.1.5-rc.x）：尺寸写进名字，如 `IconFolderOpenOutline16`；
+ *   - dsh 0.1.7+：去掉尺寸后缀、改为字重后缀，如 `IconFolderOpenOutlineRegular` /
+ *     `IconFolderOpenOutlineMedium`，尺寸改由 `size` prop 传入。
+ * ui-primitives 是 web shell 的冻结 seed 模块（不是插件行），插件无法固定它，
+ * 同一份产物会拿到宿主那一版的导出；直接按某一版的名字解构会在另一版上得到
+ * `undefined`，React 渲染时抛 "Element type is invalid" 把面板整个打崩。
+ *
+ * 因此这里按旧名导出同名组件，运行时在两个名字里取存在的那个，并把旧名里的
+ * 尺寸作为默认 `size`（两版的图标都接受 `size` prop，0.1.5 的默认值正是旧名后缀）。
+ * 两版都没有该名字时降级为空组件并告警，而不是让面板崩溃。
+ */
+import { createElement, type ComponentType } from 'react'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+
+type IconProps = { size?: number; className?: string }
+type IconComponent = ComponentType<IconProps>
+
+const table = primitives as unknown as Record<string, unknown>
+
+function resolveIcon(names: readonly string[]): IconComponent | null {
+  for (const name of names) {
+    const candidate = table[name]
+    if (typeof candidate === 'function' || (typeof candidate === 'object' && candidate !== null)) {
+      return candidate as IconComponent
+    }
+  }
+  return null
+}
+
+function icon(legacyName: string, currentName: string, defaultSize: number): IconComponent {
+  const impl = resolveIcon([legacyName, currentName])
+  if (impl === null) {
+    console.warn(
+      `[dsh-project-memory] host ui-primitives exports neither ${legacyName} nor ${currentName}; that icon renders nothing`,
+    )
+    return function MissingIcon() {
+      return null
+    }
+  }
+  function CompatIcon({ size = defaultSize, ...rest }: IconProps) {
+    return createElement(impl as IconComponent, { size, ...rest })
+  }
+  CompatIcon.displayName = legacyName
+  return CompatIcon
+}
+
+export const IconChevronDownOutline14 = icon('IconChevronDownOutline14', 'IconChevronDownOutlineRegular', 14)
+export const IconChevronUpOutline14 = icon('IconChevronUpOutline14', 'IconChevronUpOutlineRegular', 14)
+export const IconQuestionOutline14 = icon('IconQuestionOutline14', 'IconQuestionOutlineRegular', 14)
+export const IconCloseOutline16 = icon('IconCloseOutline16', 'IconCloseOutlineRegular', 16)
+export const IconFolderOpenOutline16 = icon('IconFolderOpenOutline16', 'IconFolderOpenOutlineRegular', 16)
+export const IconCheckOutline16 = icon('IconCheckOutline16', 'IconCheckOutlineRegular', 16)
+export const IconPlayOutline16 = icon('IconPlayOutline16', 'IconPlayOutlineRegular', 16)
+
+// `/` 菜单行图标。旧名的尺寸后缀两版并不一致（有的是 14 有的是 16），
+// 所以这里的默认 size 只影响"宿主两版都没有该名字"的降级路径——正常路径由宿主自己决定。
+export const IconChecklistOutline16 = icon('IconChecklistOutline14', 'IconChecklistOutlineRegular', 14)
+export const IconLightOutline16 = icon('IconLightOutline16', 'IconLightOutlineRegular', 16)
+export const IconGlobeOutline16 = icon('IconGlobeOutline14', 'IconGlobeOutlineRegular', 14)

package/src/client/locales.ts

@@ -74,6 +74,13 @@ export const zh = {
   'mem.saved': '已保存',
   'mem.edit': '编辑',
   'mem.section-label': '任务记忆',
+  // `/` 菜单：自建 slash 源的行文案。分组标题走候选的 section（见 slash.ts），
+  // 不走 slash.menu 词典——那个 namespace 由宿主的 ui-input-trigger 独占，重复注册会抛错。
+  // 三个行标题直接复用上面面板的 view.* 文案，保证菜单与面板叫同一个名字。
+  'slash.group': '工作流',
+  'slash.tasks-desc': '任务清单：步骤进度、涉及文件、当前会话绑定',
+  'slash.project-desc': '项目记忆：本项目的教训 / 决策 / 流程',
+  'slash.global-desc': '全局记忆：跨项目的经验条目',
 }
 
 export const en = {
@@ -149,6 +156,10 @@ export const en = {
   'mem.saved': 'Saved',
   'mem.edit': 'Edit',
   'mem.section-label': 'Task memory',
+  'slash.group': 'Workflow',
+  'slash.tasks-desc': 'Task list: progress, involved files, current session binding',
+  'slash.project-desc': 'Project memory: this project’s lessons / decisions / procedures',
+  'slash.global-desc': 'Global memory: experience entries shared across projects',
 }
 
 export type LocaleDict = typeof zh

package/src/client/session-id.js

@@ -0,0 +1,88 @@
+/**
+ * 会话列表快照 → 当前会话 id（宿主版本兼容层）。
+ *
+ * 快照结构被宿主改过一次，旧写法只认第一种：
+ *   - dsh ≤0.1.6：`{ current?: id, items: [{ sessionId, blank }] }`
+ *   - dsh 0.1.7+：`{ ids: id[], byId: Record<id, SessionSummary>, phase, projectionsBySession }`
+ *     —— `current` 与 `items` **都不存在了**。
+ *
+ * 后果一（永远 null）：0.1.7 上 `snap.current` 和 `snap.items` 都是 undefined → 旧代码永远
+ * 返回 null → 面板显示「还没有会话」、记忆视图报 `同步失败: no session / commands service`。
+ * 而**任务视图渲染的是 task-data-store 里的缓存快照**，看起来还正常，所以这个故障很容易被
+ * 误读成"数据格式/旧版本兼容"问题。
+ *
+ * 后果二（不跟随切换）：光"取一个非 null 的 id"不够 —— 兜底取的是宿主列表里第一个非 blank 的
+ * 会话，它**不随用户切换对话而变化**，面板会一直停在同一个会话（从而显示错项目的任务）。
+ * 0.1.7 判断"当前会话"的正式依据是 `SessionSummary.retainedBy.mainView > 0`：
+ * 主视图正在 retain 的那个就是用户正在看的那个（第一方同款判据，见 ui-layout/DocumentTitle.tsx
+ * 与 ui-session）。它就在**列表快照的 byId 行上**，而 retain 计数变化会 `list.set(...)` 重新发布
+ * 快照（session-controller/.../sessions/service.ts 的 publishRetention），所以订阅
+ * `ctx.sessions.list` 的组件会在切换会话时自动重渲染 —— 这条必须走快照内字段，不能另开
+ * `retainInfo()` 订阅，否则切换不会触发重渲染。
+ *
+ * 实测形状见 `packages/api/session-controller/src/client/sessions/service.ts` 的
+ * `SessionListState` / `SessionSummary`。
+ */
+
+/** 正数才算持有（retain 计数缺失/0/负数一律当没有）。 */
+function heldCount(value) {
+  return typeof value === 'number' && value > 0 ? value : 0
+}
+
+/** 从一行 summary 抽出本模块关心的三个事实。 */
+function rowFacts(row) {
+  return {
+    blank: row?.blank === true,
+    /** 主视图对这条会话的 retain 计数；> 0 即"用户正在看它"。 */
+    mainView: heldCount(row?.retainedBy?.mainView),
+  }
+}
+
+/**
+ * 把两种快照形状统一成 `{ id, blank, mainView }` 列表，顺序保持宿主给的顺序。
+ * @param {object|undefined|null} snap - `ctx.sessions.list.getSnapshot()`
+ * @returns {Array<{id: string, blank: boolean, mainView: number}>} 认不出的形状返回空数组
+ */
+export function sessionRows(snap) {
+  if (!snap || typeof snap !== 'object') return []
+  // 旧形状：items 里每行自带 sessionId / blank / retainedBy
+  if (Array.isArray(snap.items)) {
+    return snap.items
+      .map((row) => ({ id: row?.sessionId, ...rowFacts(row) }))
+      .filter((row) => typeof row.id === 'string' && row.id !== '')
+  }
+  const byId = snap.byId && typeof snap.byId === 'object' ? snap.byId : null
+  // 0.1.7 形状：ids 表达宿主列表成员（顺序权威），行数据在 byId 里
+  if (Array.isArray(snap.ids)) {
+    return snap.ids
+      .map((id) => ({ id, ...rowFacts(byId?.[id]) }))
+      .filter((row) => typeof row.id === 'string' && row.id !== '')
+  }
+  // 只有 byId 的半成品形状：仍然可用，只是丢了宿主顺序
+  if (byId) {
+    return Object.keys(byId)
+      .map((id) => ({ id, ...rowFacts(byId[id]) }))
+      .filter((row) => typeof row.id === 'string' && row.id !== '')
+  }
+  return []
+}
+
+/**
+ * 选出一个可用于执行命令的会话 id（即"用户正在看的那个"）。
+ *
+ * 优先级：
+ *  1. 旧形状的显式 `current`（≤0.1.6 的权威字段，保持原语义）；
+ *  2. `retainedBy.mainView > 0` 的会话（0.1.7 的权威判据，**跟随会话切换**）；
+ *  3. 第一个非 blank → 第一个（对两种形状都适用的兜底）。
+ * @param {object|undefined|null} snap - `ctx.sessions.list.getSnapshot()`
+ * @returns {string|null} 会话 id；拿不到返回 null（调用方据此显示「还没有会话」）
+ */
+export function pickSessionId(snap) {
+  if (!snap || typeof snap !== 'object') return null
+  if (typeof snap.current === 'string' && snap.current !== '') return snap.current
+  const rows = sessionRows(snap)
+  const live = rows.find((row) => row.mainView > 0)
+  if (live) return live.id
+  const chosen = rows.find((row) => !row.blank) ?? rows[0]
+  return chosen ? chosen.id : null
+}