@chenkai114/dsh-team-admin 0.0.0-stage → 0.1.1

package/src/dismiss.mjs

@@ -0,0 +1,250 @@
+// 删除角色：先停会话（中断 + 轮询等它退出），再把成员会话目录移进
+// <dataDir>/trash/<leadSessionId>/<memberId>-<毫秒>/，最后写墓碑。
+// 移动而不是删除：可恢复，且 session-query 索引会按「文件消失」自动摘除。
+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'
+
+/** 停止成员的总等待上限（契约固定 15s）。 */
+const DEFAULT_INTERRUPT_TIMEOUT_MS = 15_000
+/** 轮询成员状态的间隔。 */
+const STOP_POLL_MS = 100
+/** 回收站目录名。 */
+const TRASH_DIR = 'trash'
+
+/** 取宿主服务（可选依赖一律走 ctx.get，避免未声明的 inject 抛错）。 */
+function service(ctx, name) {
+  if (ctx === null || typeof ctx !== 'object') return undefined
+  if (typeof ctx.get === 'function') {
+    try {
+      const value = ctx.get(name)
+      if (value !== undefined && value !== null) return value
+    } catch {
+      // 服务未提供：退回属性访问。
+    }
+  }
+  try {
+    return ctx[name]
+  } catch {
+    return undefined
+  }
+}
+
+/** 普通对象判定。 */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 睡一会（仅用于停止轮询）。 */
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 还原持久化后端对路径片的编码（非安全字符编码成 ~XXXX），用于判断某个目录是否就是该会话的目录。
+ * @param {string} segment - 路径片。
+ * @returns {string} 还原后的文本。
+ */
+function decodeSegment(segment) {
+  return segment.replace(/~([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+}
+
+/**
+ * 定位要移动的源路径：优先整个会话目录（同一会话的多个 format generation 一起走），
+ * 否则只移动该会话的日志文件。
+ * @param {string} locationPath - 持久化后端给出的会话产物路径。
+ * @param {string} memberId - 成员会话 id。
+ * @returns {Promise<{path: string, isDirectory: boolean}|undefined>} 源路径；产物已不存在时为 undefined。
+ */
+async function resolveSource(locationPath, memberId) {
+  const info = await lstat(locationPath).catch(() => undefined)
+  if (info === undefined) return undefined
+  if (info.isDirectory()) return { path: locationPath, isDirectory: true }
+  const parent = dirname(locationPath)
+  if (decodeSegment(basename(parent)) === memberId) {
+    const parentInfo = await lstat(parent).catch(() => undefined)
+    if (parentInfo?.isDirectory() === true) return { path: parent, isDirectory: true }
+  }
+  return { path: locationPath, isDirectory: false }
+}
+
+/**
+ * 把一个会话产物移动到回收站目录（rename 优先；跨设备 EXDEV 时复制后删除原路径）。
+ * @param {{sourcePath: string, isDirectory?: boolean, trashRoot: string, dirName: string, renameFn?: typeof rename}} options
+ *   sourcePath 为源路径；trashRoot 为回收站根；dirName 为本次回收目录名；renameFn 仅供单测注入。
+ * @returns {Promise<string>} 回收目录绝对路径。
+ */
+export async function moveSessionArtifact({ sourcePath, isDirectory = false, trashRoot, dirName, renameFn = rename }) {
+  await mkdir(trashRoot, { recursive: true })
+  const target = join(trashRoot, dirName)
+  if (isDirectory) {
+    try {
+      await renameFn(sourcePath, target)
+      return target
+    } catch (error) {
+      if (error?.code !== 'EXDEV') throw error
+    }
+    await cp(sourcePath, target, { recursive: true, force: false, errorOnExist: false })
+    // EXDEV 兜底：复制成功后删除原目录（唯一允许删除原目录的分支，绝不用它做常规删除）。
+    await rm(sourcePath, { recursive: true, force: true })
+    return target
+  }
+  const finalPath = join(target, basename(sourcePath))
+  try {
+    await mkdir(target, { recursive: true })
+    await renameFn(sourcePath, finalPath)
+    return target
+  } catch (error) {
+    if (error?.code !== 'EXDEV') throw error
+  }
+  await mkdir(target, { recursive: true })
+  await cp(sourcePath, finalPath, { force: false, errorOnExist: false })
+  await rm(sourcePath, { force: true })
+  return target
+}
+
+/** 读 live Agent（不可用时 undefined）。 */
+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
+  }
+}
+
+/**
+ * 停掉仍在运行的成员：中断 + 轮询到非 running。
+ * @param {object} ctx - 宿主上下文。
+ * @param {{leadSessionId: string, memberId: string, timeoutMs: number, logSystem: (line: string) => void}} request - 根会话、成员、等待上限、日志函数。
+ * @returns {Promise<boolean>} 是否中断并等到退出（本来就没在运行 → false）。
+ * @throws {AdminError} 超过等待上限仍 running（409）。
+ */
+async function stopMember(ctx, { leadSessionId, memberId, timeoutMs, logSystem }) {
+  if (liveAgent(ctx, memberId)?.status !== 'running') return false
+  const leadAgent = liveAgent(ctx, leadSessionId)
+  const subagents = service(ctx, 'subagents')
+  if (subagents !== undefined && typeof subagents.interrupt === 'function') {
+    if (leadAgent === undefined) {
+      logSystem('[team-admin] 无法中断 ' + memberId + '：Lead Agent 未加载，缺少授权对象')
+    } else {
+      try {
+        subagents.interrupt(memberId, { kind: 'ancestor', agent: leadAgent })
+      } catch (error) {
+        logSystem('[team-admin] 中断 ' + memberId + ' 失败：' + String(error?.message ?? error))
+      }
+    }
+  }
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (liveAgent(ctx, memberId)?.status !== 'running') return true
+    if (Date.now() >= deadline) break
+    await delay(STOP_POLL_MS)
+  }
+  throw new AdminError('成员仍在运行，已尝试中断，请稍后重试', 'running', 409)
+}
+
+/**
+ * 删除一个团队成员：停会话 → 子会话目录进回收站 → 写墓碑。
+ * @param {object} ctx - 宿主上下文（sessionPersistence / agents / subagents 均可选）。
+ * @param {{sessionId: string, name: string, deleteSession?: boolean}} request - 根会话、成员名、是否清理子会话（默认 true）。
+ * @param {{store?: object, now?: number|(() => number), logSystem?: (line: string) => void, interruptTimeoutMs?: number}} [options]
+ *   store 为墓碑存储；now 为墓碑时间戳；interruptTimeoutMs 为停止等待上限（默认 15s）。
+ * @returns {Promise<{name: string, id: string, stopped: boolean, sessionDeleted: boolean, trashPath?: string, dismissedAt: number}>} 删除结果。
+ * @throws {AdminError} not-found / bad-session / lead / provisioning / running / system。
+ */
+export async function dismissMember(ctx, request, options = {}) {
+  const { sessionId, name } = request ?? {}
+  const deleteSession = request?.deleteSession !== false
+  const { store, logSystem = () => {}, interruptTimeoutMs = DEFAULT_INTERRUPT_TIMEOUT_MS } = options ?? {}
+  const stamp = typeof options?.now === 'function' ? Number(options.now()) : Number.isFinite(options?.now) ? Number(options.now) : Date.now()
+
+  if (typeof sessionId !== 'string' || sessionId === '' || typeof name !== 'string' || name === '') {
+    throw new AdminError('缺少 sessionId 或 name', 'bad-request', 400)
+  }
+  if (name === 'lead') throw new AdminError('不能删除 Lead', 'lead', 400)
+  if (store === undefined || store === null) throw new AdminError('墓碑存储不可用', 'system', 500)
+
+  const persistence = service(ctx, 'sessionPersistence')
+  if (persistence === undefined || typeof persistence.stat !== 'function') {
+    throw new AdminError('宿主会话服务不可用，无法删除成员', 'system', 500)
+  }
+  const snapshot = await statSnapshot(persistence, sessionId)
+  if (snapshot === undefined) throw new AdminError('会话不存在', 'not-found', 404)
+  if (snapshot.header.parentSession !== undefined) {
+    throw new AdminError('只能管理根会话的团队', 'bad-session', 400)
+  }
+
+  const log = await readSessionLog(persistence, sessionId)
+  const roster = parseRoster(log.events)
+  const member = roster.members.find((candidate) => candidate.name === name)
+  if (member === undefined) throw new AdminError('团队成员不存在', 'not-found', 404)
+  const memberId = String(member.id)
+
+  // 幂等：已墓碑的成员直接复用原记录，不重复中断 / 移动。
+  if (typeof store.listDismissed === 'function') {
+    const existing = (await store.listDismissed(sessionId)).find((row) => row.id === memberId)
+    if (existing !== undefined) {
+      return {
+        name: existing.name === undefined ? name : existing.name,
+        id: memberId,
+        stopped: false,
+        sessionDeleted: existing.sessionDeleted === true,
+        ...typeof existing.trashPath === 'string' ? { trashPath: existing.trashPath } : {},
+        dismissedAt: existing.dismissedAt,
+      }
+    }
+  }
+
+  if (member.phase === 'provisioning') {
+    throw new AdminError('成员正在创建中，请稍后再试', 'provisioning', 409)
+  }
+
+  const stopped = await stopMember(ctx, { leadSessionId: sessionId, memberId, timeoutMs: interruptTimeoutMs, logSystem })
+
+  let sessionDeleted = false
+  let trashPath
+  if (deleteSession) {
+    const child = await statSnapshot(persistence, memberId)
+    const locationPath = child?.location?.path
+    if (typeof locationPath !== 'string' || locationPath === '') {
+      logSystem('[team-admin] 成员 ' + memberId + ' 没有可移动的会话产物（未落盘或已清理）')
+    } else {
+      const source = await resolveSource(locationPath, memberId)
+      if (source === undefined) {
+        logSystem('[team-admin] 成员 ' + memberId + ' 的会话产物已不存在：' + locationPath)
+      } else {
+        try {
+          trashPath = await moveSessionArtifact({
+            sourcePath: source.path,
+            isDirectory: source.isDirectory,
+            trashRoot: join(store.dataDir, TRASH_DIR, sessionId),
+            dirName: memberId + '-' + stamp,
+          })
+          sessionDeleted = true
+        } catch (error) {
+          logSystem('[team-admin] 移动成员 ' + memberId + ' 的会话失败：' + String(error?.stack ?? error))
+          throw new AdminError('成员会话移动失败，请检查服务端日志', 'system', 500)
+        }
+      }
+    }
+  }
+
+  const record = await store.record(sessionId, memberId, {
+    name: isRecord(member) && typeof member.name === 'string' ? member.name : name,
+    dismissedAt: stamp,
+    sessionDeleted,
+    ...trashPath === undefined ? {} : { trashPath },
+  })
+  return {
+    name: record.name,
+    id: memberId,
+    stopped,
+    sessionDeleted: record.sessionDeleted === true,
+    ...typeof record.trashPath === 'string' ? { trashPath: record.trashPath } : {},
+    dismissedAt: record.dismissedAt,
+  }
+}

package/src/error.mjs

@@ -0,0 +1,16 @@
+/** 本插件统一的业务错误：带机器可读 code 与 HTTP 状态。 */
+
+/** 业务错误。code 供日志/前端分支使用，message 中文直出。 */
+export class AdminError extends Error {
+  /**
+   * @param {string} message - 面向用户的中文文案。
+   * @param {string} [code] - 机器可读错误码。
+   * @param {number} [status] - HTTP 状态码。
+   */
+  constructor(message, code = 'system', status = 400) {
+    super(message)
+    this.name = 'AdminError'
+    this.code = code
+    this.status = status
+  }
+}

package/src/index.js

@@ -0,0 +1,64 @@
+// dsh-team-admin 宿主半区入口：给「智能体团队」补管理接口 /api/team-admin/*。
+// 只读会话持久化与 live Agent 状态，不依赖内置 agent-team 的私有实现；
+// 删除动作 = 停会话 → 子会话目录进回收站 → 写墓碑（内置 roster 是 append-only，记录仍在）。
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { createApi } from './api.mjs'
+import { dismissMember } from './dismiss.mjs'
+import { openStore } from './store.mjs'
+import { listTeamSessions, readTeam } from './team-read.mjs'
+
+export const name = 'team-admin'
+export const inject = ['webServer']
+
+/** 数据目录环境变量（测试注入临时目录）。 */
+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'
+
+/**
+ * 解析插件数据目录。
+ * @param {NodeJS.ProcessEnv} [env] - 进程环境。
+ * @param {string} [home] - 用户主目录。
+ * @returns {string} 数据目录绝对路径。
+ */
+export function resolveDataDir(env = process.env, home = homedir()) {
+  const override = env[DATA_DIR_ENV]
+  if (typeof override === 'string' && override.trim() !== '') return override.trim()
+  return join(home, '.dsh', 'team-admin')
+}
+
+/**
+ * 装配插件：惰性建 store，注册一条 prefix 路由。
+ * @param {object} ctx - Cordis 插件上下文。
+ */
+export function apply(ctx) {
+  const dataDir = resolveDataDir()
+  let storePromise = null
+  const getStore = () => {
+    if (storePromise === null) {
+      storePromise = openStore({ dir: dataDir }).catch((error) => {
+        storePromise = null
+        throw error
+      })
+    }
+    return storePromise
+  }
+  const logSystem = (line) => {
+    if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(line)
+  }
+  const handler = createApi({
+    ctx,
+    getStore,
+    version: PLUGIN_VERSION,
+    logSystem,
+    services: { listTeamSessions, readTeam, dismissMember },
+  })
+  ctx.effect(
+    () => ctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler }),
+    'team-admin routes',
+  )
+}

package/src/store.mjs

@@ -0,0 +1,175 @@
+// 墓碑存储：state.json 单文件 + 进程内写链。
+// 写 = 同目录临时文件 + rename（原子替换）；坏 JSON / 未知 version 改名 .corrupt-<ts> 后按空状态处理。
+
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 当前状态文件格式版本；其他版本一律按损坏处理。 */
+const STATE_VERSION = 1
+/** 状态文件名（位于 dataDir 下）。 */
+const STATE_FILE = 'state.json'
+
+/** 空状态：无任何墓碑。 */
+function emptyState() {
+  return { version: STATE_VERSION, dismissed: {} }
+}
+
+/** 普通对象判定（排除 null / 数组）。 */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** 规范化单条墓碑记录，剔除未知字段并补齐默认值。 */
+function normalizeRecord(raw) {
+  const row = {
+    name: typeof raw.name === 'string' ? raw.name : '',
+    dismissedAt: Number.isFinite(raw.dismissedAt) ? raw.dismissedAt : Date.now(),
+    sessionDeleted: raw.sessionDeleted === true,
+  }
+  if (typeof raw.trashPath === 'string' && raw.trashPath !== '') row.trashPath = raw.trashPath
+  return row
+}
+
+/**
+ * 校验并规范化整份状态。
+ * @param {unknown} raw - 解析后的 JSON 值。
+ * @returns {{version: number, dismissed: Record<string, Record<string, object>>}|undefined} 合法状态，否则 undefined。
+ */
+function normalizeState(raw) {
+  if (!isRecord(raw) || raw.version !== STATE_VERSION) return undefined
+  if (!isRecord(raw.dismissed)) return undefined
+  const dismissed = {}
+  for (const [leadId, bucket] of Object.entries(raw.dismissed)) {
+    if (!isRecord(bucket)) continue
+    const members = {}
+    for (const [memberId, record] of Object.entries(bucket)) {
+      if (isRecord(record)) members[memberId] = normalizeRecord(record)
+    }
+    dismissed[leadId] = members
+  }
+  return { version: STATE_VERSION, dismissed }
+}
+
+/** 深拷贝一条墓碑记录，附带 memberId 作为 id。 */
+function toRow(memberId, record) {
+  return { id: memberId, ...record }
+}
+
+/**
+ * 打开（必要时创建）一个墓碑存储。
+ * @param {{dir: string}} options - dir 为数据目录（不要求已存在）。
+ * @returns {Promise<{readAll: () => Promise<{version: number, dismissed: object}>, listDismissed: (leadId: string) => Promise<object[]>, record: (leadId: string, memberId: string, row: object) => Promise<object>, dataDir: string}>} 存储句柄。
+ */
+export async function openStore({ dir }) {
+  const dataDir = dir
+  const file = join(dir, STATE_FILE)
+  const tmpFile = file + '.tmp'
+  let loadPromise
+  let state
+  // 写链：同一进程内所有写串行，避免 tmp 文件互踩，并保证磁盘顺序与调用顺序一致。
+  let chain = Promise.resolve()
+
+  /** 把损坏文件改名隔离，失败不影响按空状态继续。 */
+  async function quarantine() {
+    try {
+      await rename(file, file + '.corrupt-' + Date.now())
+    } catch {
+      // 文件已不存在或不可改名：隔离失败时仍按空状态服务，避免整条路由不可用。
+    }
+  }
+
+  /** 读取 state.json（只加载一次）；缺失 → 空状态，损坏 / 未知版本 → 隔离后空状态。 */
+  async function load() {
+    let text
+    try {
+      text = await readFile(file, 'utf8')
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyState()
+      throw error
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      await quarantine()
+      return emptyState()
+    }
+    const normalized = normalizeState(parsed)
+    if (normalized === undefined) {
+      await quarantine()
+      return emptyState()
+    }
+    return normalized
+  }
+
+  /** 惰性加载状态（并发调用共享同一次加载；失败不缓存，下次重试）。 */
+  function ensureLoaded() {
+    loadPromise ??= load().then((value) => {
+      state = value
+      return value
+    }, (error) => {
+      loadPromise = undefined
+      throw error
+    })
+    return loadPromise
+  }
+
+  /** 原子落盘：写临时文件后 rename 覆盖。 */
+  async function persist() {
+    await mkdir(dataDir, { recursive: true })
+    await writeFile(tmpFile, JSON.stringify(state, null, 2), 'utf8')
+    await rename(tmpFile, file)
+  }
+
+  /** 在写链上执行一次「读状态 → 变更 → 落盘」，返回值即调用方结果。 */
+  function enqueue(task) {
+    const result = chain.then(async () => {
+      await ensureLoaded()
+      return task()
+    })
+    chain = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  return {
+    dataDir,
+    /** 读取全部墓碑（按 leadSessionId / memberId 分组，调用方拿到的是副本）。 */
+    async readAll() {
+      await ensureLoaded()
+      const dismissed = {}
+      for (const [leadId, bucket] of Object.entries(state.dismissed)) {
+        dismissed[leadId] = {}
+        for (const [memberId, record] of Object.entries(bucket)) {
+          dismissed[leadId][memberId] = toRow(memberId, record)
+        }
+      }
+      return { version: state.version, dismissed }
+    },
+    /** 列出某根会话下已删除的成员，按删除时间降序。 */
+    async listDismissed(leadId) {
+      await ensureLoaded()
+      const bucket = state.dismissed[leadId]
+      if (bucket === undefined) return []
+      return Object.entries(bucket)
+        .map(([memberId, record]) => toRow(memberId, record))
+        .sort((left, right) => right.dismissedAt - left.dismissedAt)
+    },
+    /**
+     * 记录一条墓碑；同一成员已存在时保留原记录（幂等），返回最终生效的记录。
+     * @param {string} leadId - 根会话 id。
+     * @param {string} memberId - 成员会话 id。
+     * @param {{name: string, dismissedAt: number, sessionDeleted: boolean, trashPath?: string}} row - 墓碑内容。
+     */
+    async record(leadId, memberId, row) {
+      return enqueue(async () => {
+        const bucket = state.dismissed[leadId] ?? (state.dismissed[leadId] = {})
+        const existing = bucket[memberId]
+        if (existing !== undefined) return toRow(memberId, existing)
+        const normalized = normalizeRecord(row)
+        bucket[memberId] = normalized
+        await persist()
+        return toRow(memberId, normalized)
+      })
+    },
+  }
+}