@chenkai114/dsh-team-admin 0.1.1 → 0.1.2

package/README.md

@@ -18,7 +18,7 @@ v0.2.x 的内置 Team roster 是 **append-only**：只能 `spawn_teammate` 加
 dsh plugin --profile web add @chenkai114/dsh-team-admin
 ```
 
-重启 / 重载后，打开 **设置 → 插件 → dsh-team-admin**（或插件管理页里本包的配置卡），即可看到「智能体团队管理」面板。
+重载后左侧栏会出现 **团队管理** 入口（插件市场里本包的配置卡也保留）。
 
 未发布前用本地源码链接安装：
 
@@ -34,7 +34,13 @@ dsh plugin --profile web add link:/Users/chenkai2/data1/www/htdocs/dsh-team-admi
 }
 ```
 
-![团队管理卡片](docs/images/team-admin.png)
+左侧栏「团队管理」入口（0.1.1 起）：
+
+![侧栏入口](docs/images/sidebar-entry.png)
+
+打开后是完整管理面板，可直接对真实会话操作：
+
+![团队管理面板](docs/images/team-panel-real.png)
 
 ## 用法
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenkai114/dsh-team-admin",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "DSH 插件：GUI 管理任意会话的智能体团队 —— 查看成员、删除角色并清理其持久会话（进回收站，可恢复）",
   "type": "module",
   "main": "src/index.js",

package/src/dismiss.mjs

@@ -5,7 +5,7 @@ import { cp, lstat, mkdir, rename, rm } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 
 import { AdminError } from './error.mjs'
-import { parseRoster, readSessionLog, statSnapshot } from './team-read.mjs'
+import { invalidateSessionListCache, parseRoster, readSessionLog, statSnapshot } from './team-read.mjs'
 
 /** 停止成员的总等待上限（契约固定 15s）。 */
 const DEFAULT_INTERRUPT_TIMEOUT_MS = 15_000
@@ -225,6 +225,8 @@ export async function dismissMember(ctx, request, options = {}) {
             dirName: memberId + '-' + stamp,
           })
           sessionDeleted = true
+          // 会话文件已消失：让下一轮列表 / 团队详情立刻重扫，而不是等 60s 缓存过期。
+          invalidateSessionListCache(ctx)
         } catch (error) {
           logSystem('[team-admin] 移动成员 ' + memberId + ' 的会话失败：' + String(error?.stack ?? error))
           throw new AdminError('成员会话移动失败，请检查服务端日志', 'system', 500)

package/src/index.js

@@ -17,7 +17,7 @@ const DATA_DIR_ENV = 'DSH_TEAM_ADMIN_DATA_DIR'
 /** 路由前缀：webServer 只支持 exact/prefix 注册。 */
 const ROUTE_PREFIX = '/api/team-admin'
 /** 与 package.json 版本保持一致（发布前由测试校验）。 */
-const PLUGIN_VERSION = '0.1.1'
+const PLUGIN_VERSION = '0.1.2'
 
 /**
  * 解析插件数据目录。

package/src/team-read.mjs

@@ -1,6 +1,10 @@
 // 只读半区：列根会话、读某会话的团队（成员快照 + 任务归属 + 实时状态）。
-// 标题优先走宿主的 sessionQuery 折叠；不可用时按需读会话日志并做 TTL 缓存，
-// 列表页只对真正需要的会话取标题，绝不为了标题全量解压所有会话。
+//
+// 性能约定（列表页冷启动 / 暖调用）：
+// - 会话快照列表 + mtime + live 按 ctx 缓存 60s，同一 ctx 的并发调用共享一次扫描（inFlight 去重）；
+//   query 与 limit 都在缓存结果上做，绝不每次调用都重新 list() 一遍整个会话库。
+// - 标题优先取宿主的 projection cache（sessionProjectionCache，零 I/O 的已折叠行），
+//   其次 sessionQuery 批量折叠，最后按上限读日志前缀；不会为了标题全量解压会话。
 import { stat } from 'node:fs/promises'
 
 import { AdminError } from './error.mjs'
@@ -8,16 +12,25 @@ import { AdminError } from './error.mjs'
 /** 默认列表条数与上限（与 src/api.mjs 保持一致）。 */
 const DEFAULT_LIMIT = 50
 const MAX_LIMIT = 200
-/** 无 sessionQuery 时最多为多少个会话折叠标题（按最近活动取前 N）。 */
-const TITLE_SCAN_LIMIT = 400
-/** 标题内存缓存有效期。 */
-const TITLE_TTL_MS = 30_000
-/** 回退读日志时只取前 N 条事件（用于取首条 user/message）。 */
-const TITLE_PREFIX_EVENTS = 80
-/** 并发读日志折叠标题的上限。 */
-const TITLE_CONCURRENCY = 4
-
-/** 标题缓存按 ctx 归属，避免跨插件实例 / 跨测试串味。 */
+/** 会话快照扫描缓存有效期（列表允许 1 分钟陈旧）。 */
+const SCAN_TTL_MS = 60_000
+/** 扫描时读 mtime 的并发上限，避免几千个会话同时开 fd。 */
+const SCAN_CONCURRENCY = 16
+/** 冷扫描超过该耗时打一条 warn，便于从服务端日志定位宿主存储变慢。 */
+const COLD_WARN_MS = 2_000
+/** 标题缓存有效期（与扫描缓存对齐）。 */
+const TITLE_TTL_MS = 60_000
+/** 一次 sessionQuery 批量折叠标题的上限（它读日志实现，冷启动时不能放大）。 */
+const TITLE_QUERY_LIMIT = 32
+/** 一次为标题读日志前缀的会话数上限。 */
+const PREFIX_READ_LIMIT = 16
+/** 读日志前缀时最多取的事件数。 */
+const PREFIX_EVENTS = 80
+/** 前缀读取并发上限。 */
+const PREFIX_CONCURRENCY = 2
+
+/** 会话扫描缓存与标题缓存都按 ctx 归属，避免跨插件实例 / 跨测试串味。 */
+const scanStates = new WeakMap()
 const titleCaches = new WeakMap()
 
 /** 取宿主服务（可选依赖用 ctx.get，避免未声明的 inject 抛错）。 */
@@ -38,14 +51,13 @@ function service(ctx, name) {
   }
 }
 
-/** 当前 ctx 的标题缓存。 */
-function titleCache(ctx) {
-  let cache = titleCaches.get(ctx)
-  if (cache === undefined) {
-    cache = new Map()
-    titleCaches.set(ctx, cache)
+/** 打一条宿主 warn（日志不可用时静默）。 */
+function logWarn(ctx, message) {
+  try {
+    if (typeof ctx?.logger?.warn === 'function') ctx.logger.warn(message)
+  } catch {
+    // 日志输出失败不影响接口结果。
   }
-  return cache
 }
 
 /** 普通对象判定。 */
@@ -98,7 +110,7 @@ export async function readSessionLog(persistence, sessionId) {
   }
 }
 
-/** 会话文件 mtime（未知 → undefined）；用于「最近活动」近似值。 */
+/** 会话产物文件 mtime（未知 → undefined）；用于「最近活动」近似值。 */
 async function artifactMtime(path) {
   if (typeof path !== 'string' || path === '') return undefined
   try {
@@ -124,14 +136,132 @@ async function mapLimited(items, limit, fn) {
   return results
 }
 
+/** 某个 ctx 的会话扫描缓存槽。 */
+function scanState(ctx) {
+  let state = scanStates.get(ctx)
+  if (state === undefined) {
+    state = { at: 0, rows: undefined, headers: undefined, inFlight: undefined }
+    scanStates.set(ctx, state)
+  }
+  return state
+}
+
+/** 当前 ctx 的标题缓存。 */
+function titleCache(ctx) {
+  let cache = titleCaches.get(ctx)
+  if (cache === undefined) {
+    cache = new Map()
+    titleCaches.set(ctx, cache)
+  }
+  return cache
+}
+
 /**
- * 折叠一批会话的标题（缓存 + sessionQuery 批量优先 + 按需读日志兜底）。
+ * 丢弃某个 ctx 的会话扫描缓存（删除成员后可让列表 / 团队详情立刻反映文件变化）。
+ * @param {object} ctx - 宿主上下文。
+ */
+export function invalidateSessionListCache(ctx) {
+  scanStates.delete(ctx)
+}
+
+/** 一个会话的最近活动时间（未知回退创建时间）。 */
+async function lastActivityOf(snapshot) {
+  const mtime = await artifactMtime(snapshot?.location?.path)
+  return mtime ?? (Number(snapshot?.header?.createdAt) || 0)
+}
+
+/** 实时状态：ctx.agents.get(id) 有值即已加载。 */
+function liveAgent(ctx, id) {
+  const agents = service(ctx, 'agents')
+  if (agents === undefined || typeof agents.get !== 'function') return undefined
+  try {
+    return agents.get(id)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 扫一次会话库（含全部会话，不只是根会话），结果按 ctx 缓存。
+ * 同一 ctx 的并发冷调用共享同一次扫描；扫描失败且存在旧缓存时先给旧数据。
  * @param {object} ctx - 宿主上下文。
- * @param {string[]} ids - 需要标题的会话 id。
  * @param {object} persistence - ctx.sessionPersistence。
- * @returns {Promise<Map<string, string>>} 已知标题（缺标题的会话映射为 id）。
+ * @param {{maxAgeMs?: number}} [options] - 缓存有效期覆盖（默认 60s，0 表示强制重扫）。
+ * @returns {Promise<{at: number, rows: object[], headers: Map<string, object>}>} 缓存槽（含全部会话行）。
+ * @throws {AdminError} 首次扫描失败（无旧缓存可退）。
  */
-async function collectTitles(ctx, ids, persistence) {
+async function scanSessions(ctx, persistence, { maxAgeMs = SCAN_TTL_MS } = {}) {
+  const state = scanState(ctx)
+  if (state.rows !== undefined && Date.now() - state.at < maxAgeMs) return state
+  if (state.inFlight !== undefined) return state.inFlight
+
+  const started = Date.now()
+  state.inFlight = (async () => {
+    const snapshots = await persistence.list()
+    const rows = []
+    const headers = new Map()
+    await mapLimited(snapshots, SCAN_CONCURRENCY, async (snapshot) => {
+      if (!isRecord(snapshot?.header)) return
+      const id = String(snapshot.header.id)
+      headers.set(id, snapshot.header)
+      rows.push({
+        id,
+        cwd: typeof snapshot.header.cwd === 'string' ? snapshot.header.cwd : '',
+        createdAt: Number(snapshot.header.createdAt) || 0,
+        lastActivityAt: await lastActivityOf(snapshot),
+        live: liveAgent(ctx, id) !== undefined,
+        parentSession: snapshot.header.parentSession,
+      })
+    })
+    state.rows = rows
+    state.headers = headers
+    state.at = Date.now()
+    const took = state.at - started
+    if (took >= COLD_WARN_MS) {
+      logWarn(ctx, '[team-admin] 会话列表冷扫描耗时 ' + took + 'ms（' + rows.length + ' 个会话，缓存 ' + Math.round(SCAN_TTL_MS / 1000) + 's）')
+    }
+    return state
+  })()
+
+  try {
+    return await state.inFlight
+  } catch (error) {
+    if (state.rows !== undefined) {
+      logWarn(ctx, '[team-admin] 会话扫描失败，继续使用 ' + Math.round((Date.now() - state.at) / 1000) + 's 前的缓存：' + String(error?.message ?? error))
+      return state
+    }
+    throw error
+  } finally {
+    state.inFlight = undefined
+  }
+}
+
+/**
+ * 从宿主 projection cache 取已折叠标题（同步零 I/O，与宿主冷列表一致）。
+ * @param {object} projections - ctx.sessionProjectionCache。
+ * @param {object} header - 会话头部（生命周期身份校验用）。
+ * @returns {string|undefined} 标题；无可用行时 undefined。
+ */
+function projectionTitle(projections, header) {
+  if (projections === undefined || header === undefined || typeof projections.cachedSnapshot !== 'function') return undefined
+  try {
+    const block = projections.cachedSnapshot(header, ['title'])
+    const value = block?.values?.title
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 折叠一批会话的标题（缓存 → projection cache → sessionQuery 批量 → 日志前缀 → 会话 id）。
+ * @param {object} ctx - 宿主上下文。
+ * @param {string[]} ids - 需要标题的会话 id。
+ * @param {object} persistence - ctx.sessionPersistence（前缀读取兜底用）。
+ * @param {Map<string, object>} [headers] - id → 会话头部（projection cache 身份校验用）。
+ * @returns {Promise<Map<string, string>>} 标题表（读不到的会话映射为 id）。
+ */
+async function collectTitles(ctx, ids, persistence, headers = new Map()) {
   const cache = titleCache(ctx)
   const now = Date.now()
   const titles = new Map()
@@ -148,40 +278,46 @@ async function collectTitles(ctx, ids, persistence) {
     titles.set(id, title)
   }
 
-  const query = service(ctx, 'sessionQuery')
-  const usable = query !== undefined && typeof query.readTitleSnapshots === 'function'
+  // 1) 宿主 projection cache：同步命中，冷列表的主要标题来源。
+  const projections = service(ctx, 'sessionProjectionCache')
   const unresolved = []
-  let batchWorked = false
-  if (usable) {
+  for (const id of pending) {
+    const title = projectionTitle(projections, headers.get(id))
+    if (title === undefined) unresolved.push(id)
+    else remember(id, title)
+  }
+
+  // 2) sessionQuery 批量折叠：它按日志实现，只在剩余量可控时才调用，避免冷启动放大。
+  let remaining = unresolved
+  const query = service(ctx, 'sessionQuery')
+  if (remaining.length > 0 && remaining.length <= TITLE_QUERY_LIMIT
+    && query !== undefined && typeof query.readTitleSnapshots === 'function') {
     let results
     try {
-      results = await query.readTitleSnapshots(pending)
+      results = await query.readTitleSnapshots(remaining)
     } catch {
       results = undefined
     }
     if (Array.isArray(results)) {
-      batchWorked = true
+      const stillOpen = []
       for (const [index, item] of results.entries()) {
-        const id = typeof item?.sessionId === 'string' ? item.sessionId : pending[index]
+        const id = typeof item?.sessionId === 'string' ? item.sessionId : remaining[index]
         const title = item?.status === 'fulfilled' ? item.value?.title?.title : undefined
         if (typeof title === 'string' && title.trim() !== '') remember(id, title.trim())
-        else unresolved.push(id)
+        else stillOpen.push(id)
       }
-    } else {
-      unresolved.push(...pending)
+      remaining = stillOpen
     }
-  } else {
-    unresolved.push(...pending)
   }
 
-  // 批量折叠成功说明「没有标题」是权威结论，此时只读前缀找首条用户消息；
-  // 批量不可用（无 sessionQuery 或整批失败）才读全量日志折叠最后一条 session/title。
-  await mapLimited(unresolved, TITLE_CONCURRENCY, async (id) => {
+  // 3) 有上限的日志前缀读取：取 session/title 或首条 user/message，绝不整篇解压。
+  const prefixIds = remaining.slice(0, PREFIX_READ_LIMIT)
+  await mapLimited(prefixIds, PREFIX_CONCURRENCY, async (id) => {
     try {
       const handle = await persistence.open(id, 'read')
       let events
       try {
-        const slice = await handle.read(0, batchWorked ? TITLE_PREFIX_EVENTS : undefined)
+        const slice = await handle.read(0, PREFIX_EVENTS)
         events = slice.events
       } finally {
         await handle.close()
@@ -192,61 +328,53 @@ async function collectTitles(ctx, ids, persistence) {
       // 会话不可读（已进回收站 / 被打断写坏）：标题回退会话 id，不影响列表。
     }
   })
-  // 读不到标题的会话按会话 id 兜底，一并进缓存，避免每次列表都重读同一个坏会话。
-  for (const id of unresolved) if (!titles.has(id)) remember(id, id)
+
+  // 4) 兜底：读不到标题的会话按会话 id 记住，避免每次列表都重读同一个坏会话。
+  for (const id of pending) if (!titles.has(id)) remember(id, id)
   return titles
 }
 
-/** 一个会话的最近活动时间（未知回退创建时间）。 */
-async function lastActivityOf(snapshot) {
-  const mtime = await artifactMtime(snapshot?.location?.path)
-  return mtime ?? (Number(snapshot?.header?.createdAt) || 0)
+/** 把内部扫描行换成对外的 SessionRow（只输出契约字段）。 */
+function toSessionRow(row, title) {
+  return {
+    id: row.id,
+    title,
+    cwd: row.cwd,
+    createdAt: row.createdAt,
+    lastActivityAt: row.lastActivityAt,
+    live: row.live,
+  }
 }
 
-/** 实时状态：ctx.agents.get(id) 有值即已加载。 */
-function liveAgent(ctx, id) {
-  const agents = service(ctx, 'agents')
-  if (agents === undefined || typeof agents.get !== 'function') return undefined
-  try {
-    return agents.get(id)
-  } catch {
-    return undefined
-  }
+/** 列表排序：最近活动降序，其次创建时间降序，最后按 id 保证稳定。 */
+function compareActivity(left, right) {
+  return right.lastActivityAt - left.lastActivityAt
+    || right.createdAt - left.createdAt
+    || left.id.localeCompare(right.id)
 }
 
 /**
  * 列根会话（parentSession 为空），按最近活动降序。
  * @param {object} ctx - 宿主上下文。
- * @param {{query?: string, limit?: number}} [options] - 搜索词与条数上限。
+ * @param {{query?: string, limit?: number, maxAgeMs?: number}} [options] - 搜索词、条数上限、扫描缓存有效期覆盖。
  * @returns {Promise<object[]>} SessionRow 数组。
  */
-export async function listTeamSessions(ctx, { query = '', limit = DEFAULT_LIMIT } = {}) {
+export async function listTeamSessions(ctx, { query = '', limit = DEFAULT_LIMIT, maxAgeMs = SCAN_TTL_MS } = {}) {
   const persistence = service(ctx, 'sessionPersistence')
   if (persistence === undefined || typeof persistence.list !== 'function') {
     throw new AdminError('宿主会话服务不可用，无法列出会话', 'system', 500)
   }
   const effectiveLimit = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, MAX_LIMIT) : DEFAULT_LIMIT
-  const snapshots = (await persistence.list()).filter((snapshot) => isRecord(snapshot?.header) && snapshot.header.parentSession === undefined)
-
-  // mtime 读盘有并发上限：几千个会话时不至于同时开几千个 fd。
-  const rows = await mapLimited(snapshots, 16, async (snapshot) => {
-    const id = String(snapshot.header.id)
-    const createdAt = Number(snapshot.header.createdAt) || 0
-    return {
-      id,
-      title: id,
-      cwd: typeof snapshot.header.cwd === 'string' ? snapshot.header.cwd : '',
-      createdAt,
-      lastActivityAt: await lastActivityOf(snapshot),
-      live: liveAgent(ctx, id) !== undefined,
-    }
-  })
-  rows.sort((left, right) => right.lastActivityAt - left.lastActivityAt || right.createdAt - left.createdAt)
+  const scan = await scanSessions(ctx, persistence, { maxAgeMs })
+  const roots = scan.rows.filter((row) => row.parentSession === undefined)
+  roots.sort(compareActivity)
 
   const needle = typeof query === 'string' ? query.trim().toLowerCase() : ''
-  const titleIds = (needle === '' ? rows.slice(0, effectiveLimit) : rows.slice(0, TITLE_SCAN_LIMIT)).map((row) => row.id)
-  const titles = await collectTitles(ctx, titleIds, persistence)
-  for (const row of rows) row.title = titles.get(row.id) ?? row.id
+  // 搜索要对标题做子串匹配，因此搜索时给全部根会话取标题（标题来源都是缓存/零 I/O，
+  // 只有极少数会话才会触发前缀读取）；无搜索时只取将返回的那一段。
+  const titleIds = (needle === '' ? roots.slice(0, effectiveLimit) : roots).map((row) => row.id)
+  const titles = await collectTitles(ctx, titleIds, persistence, scan.headers)
+  const rows = roots.map((row) => toSessionRow(row, titles.get(row.id) ?? row.id))
   if (needle === '') return rows.slice(0, effectiveLimit)
   return rows
     .filter((row) => row.title.toLowerCase().includes(needle)
@@ -266,7 +394,13 @@ export function parseRoster(events) {
   const tasks = new Map()
   let title
   for (const event of events ?? []) {
-    if (!isRecord(event) || !isRecord(event.data)) continue
+    if (!isRecord(event)) continue
+    if (event.type === 'session/title' && isRecord(event.data) && typeof event.data.title === 'string') {
+      const text = event.data.title.trim()
+      if (text !== '') title = text
+      continue
+    }
+    if (!isRecord(event.data)) continue
     if (event.type === 'team/member' && isRecord(event.data.member)) {
       const member = event.data.member
       if (typeof member.id === 'string' && member.id !== '') members.set(member.id, { ...member })
@@ -280,10 +414,6 @@ export function parseRoster(events) {
       if (current === undefined || (Number.isFinite(revision) && revision >= Number(current.revision))) {
         tasks.set(task.id, { ...task })
       }
-      continue
-    }
-    if (event.type === 'session/title' && typeof event.data.title === 'string' && event.data.title.trim() !== '') {
-      title = event.data.title.trim()
     }
   }
   return {
@@ -316,7 +446,11 @@ export async function readTeam(ctx, { sessionId, store }) {
 
   const log = await readSessionLog(persistence, sessionId)
   const roster = parseRoster(log.events)
-  const title = roster.title ?? (await collectTitles(ctx, [sessionId], persistence)).get(sessionId) ?? sessionId
+  const scan = await scanSessions(ctx, persistence)
+  const headers = new Map([[sessionId, snapshot.header]])
+  const title = roster.title
+    ?? (await collectTitles(ctx, [sessionId], persistence, headers)).get(sessionId)
+    ?? sessionId
   const session = {
     id: sessionId,
     title,
@@ -326,14 +460,7 @@ export async function readTeam(ctx, { sessionId, store }) {
     live: liveAgent(ctx, sessionId) !== undefined,
   }
 
-  let childSnapshots = new Map()
-  if (typeof persistence.list === 'function') {
-    try {
-      childSnapshots = new Map((await persistence.list()).map((item) => [String(item.header.id), item]))
-    } catch {
-      childSnapshots = new Map()
-    }
-  }
+  const childRows = new Map(scan.rows.map((row) => [row.id, row]))
   const leadAgent = liveAgent(ctx, sessionId)
   const dismissedRows = store === undefined || typeof store.listDismissed !== 'function'
     ? []
@@ -343,13 +470,13 @@ export async function readTeam(ctx, { sessionId, store }) {
   const teammates = roster.members.filter((member) => member.name !== 'lead' && String(member.id) !== sessionId)
   const memberIds = new Set(teammates.map((member) => member.id))
 
-  const members = await Promise.all(teammates.map(async (member) => {
+  const members = teammates.map((member) => {
     const id = String(member.id)
     const live = liveAgent(ctx, id)
-    const child = childSnapshots.get(id)
+    const child = childRows.get(id)
     const phase = member.phase === 'failed' || member.phase === 'provisioning' ? member.phase : 'active'
     const model = live?.options?.model ?? leadAgent?.options?.model
-    const row = {
+    return {
       name: String(member.name ?? ''),
       id,
       phase,
@@ -362,10 +489,9 @@ export async function readTeam(ctx, { sessionId, store }) {
       dismissed: dismissedById.has(id),
       sessionExists: live !== undefined || child !== undefined,
       ownedTasks: roster.tasks.filter((task) => task.ownerId === id).length,
-      lastActivityAt: child === undefined ? null : await lastActivityOf(child) ?? null,
+      lastActivityAt: child === undefined ? null : child.lastActivityAt,
     }
-    return row
-  }))
+  })
 
   const dismissed = dismissedRows.map((row) => ({
     name: row.name,