@roaming-ai/dsh-group-chat 0.3.0 → 0.3.2

package/src/host/engine/retitle.ts

@@ -6,55 +6,33 @@
  */
 
 import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
+import { looseJson } from '../../core/json.ts'
 import type { SessionRecord } from '../../core/types.ts'
 import { DEFAULT_SESSION_NAME, type HostState } from '../state.ts'
+import { defaultModel, speakerNameOf } from './defaults.ts'
 
 /** 仍是新建占位名（含改名之前的「会话 N」存量），自动标题尚未落地。 */
 const isPlaceholderName = (name: string): boolean =>
   name === DEFAULT_SESSION_NAME || /^会话 \d+$/.test(name)
 
-/** DSH 默认模型（agentDefaultModel 服务缺位或未配置时返回 null，调用方静默跳过）。 */
-const defaultModel = (core: HostState): { provider: string, model: string } | null => {
-  try {
-    // cordis 语义：未 inject 的 ctx 属性访问会抛错（"cannot get property without
-    // inject"），`?.` 接不住——可选消费必须走 reflect.get（读全局注册表，缺位返回
-    // undefined）。直接属性访问曾致 retitle 被静默跳过（标题/主题从不生成）。
-    const svc = core.ctx.reflect.get('agentDefaultModel')
-    const sel = svc ? svc.currentSelection() : null
-    return sel && typeof sel.provider === 'string' && typeof sel.model === 'string' && sel.provider && sel.model
-      ? { provider: sel.provider, model: sel.model }
-      : null
-  } catch {
-    return null
-  }
-}
-
 /** 命名输入：最近 40 条非系统消息的紧凑转写（每条 500 字符封顶，命名不需要全文）。 */
 const titleTranscript = (core: HostState, sess: SessionRecord): string => {
   const out: string[] = []
   for (const mid of sess.messageIds.slice(-40)) {
     const m = core.messages.get(mid)
     if (!m || m.speaker === 'system' || m.error || !m.text) continue
-    const name = m.speaker === 'user' ? '用户' : (core.roles.get(m.speaker) || { name: undefined }).name || '成员'
-    out.push('【' + name + '】' + m.text.replace(/\s+/g, ' ').slice(0, 500))
+    out.push('【' + speakerNameOf(core.roles, m.speaker) + '】' + m.text.replace(/\s+/g, ' ').slice(0, 500))
   }
   return out.join('\n')
 }
 
-/** 宽容解析模型输出：剥代码围栏 → 取首个 { 至末个 } 的 JSON → 校验并封顶字段。 */
+/** 宽容解析模型输出：剥代码围栏 → looseJson → 校验并封顶字段。 */
 const parseRetitle = (raw: string): { name?: string, topic?: string } => {
-  const body = raw.replace(/```(?:json)?/g, '')
-  const l = body.indexOf('{')
-  const r = body.lastIndexOf('}')
-  if (l < 0 || r <= l) return {}
-  try {
-    const o = JSON.parse(body.slice(l, r + 1)) as { name?: unknown, topic?: unknown }
-    const name = typeof o.name === 'string' ? o.name.trim() : ''
-    const topic = typeof o.topic === 'string' ? o.topic.trim() : ''
-    return { name: name ? name.slice(0, 24) : undefined, topic: topic ? topic.slice(0, 120) : undefined }
-  } catch {
-    return {}
-  }
+  const o = looseJson(raw.replace(/```(?:json)?/g, ''))
+  if (!o) return {}
+  const name = typeof o.name === 'string' ? o.name.trim() : ''
+  const topic = typeof o.topic === 'string' ? o.topic.trim() : ''
+  return { name: name ? name.slice(0, 24) : undefined, topic: topic ? topic.slice(0, 120) : undefined }
 }
 
 /**

package/src/host/materials/materials.ts

@@ -64,6 +64,8 @@ export function createMaterials(core: HostState): Materials {
 
   /** 逐候选 stat，返回第一个存在的目标；都不存在时返回首候选与全部尝试。 */
   const resolveMaterialTarget = async (raw: unknown) => {
+    // candidatePaths 构造上恒返回非空候选数组（'' → [HOME]，其余分支均单值或
+    // 非空 map），first 必在；! 仅为取首候选，无空指针风险
     const candidates = await candidatePaths(raw)
     let first: { target: import('@deepseek-ai/dsh-fs').FsTarget, path: string } | undefined
     for (const c of candidates) {

package/src/host/persistence/persistence.ts

@@ -5,6 +5,7 @@
  */
 
 import { existsSync } from 'node:fs'
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
 import { repairFailedMessage } from '../../core/errors.ts'
 import { messageJson, roleJson } from '../../core/json.ts'
 import { sanitizeConstraints } from '../../core/constraints.ts'
@@ -25,6 +26,9 @@ interface SessionDocument {
   messages?: Partial<MessageRecord>[]
 }
 
+/** writeFileAtomic 权限位：私有数据 0o600、目录 0o700（对齐 Store.atomicWrite）。 */
+const WRITE_FILE_OPTS = { mode: 0o600, dirMode: 0o700 } as const
+
 /** 群组角色文件形态（hydrate 用）。 */
 interface RolesDocument {
   roles?: Partial<RoleRecord>[]
@@ -34,12 +38,10 @@ interface RolesDocument {
 export interface Persistence {
   /** 事件驱动落盘；同一 tick 内多次变更合并为一次写。 */
   schedulePersist: (targets?: { ledger?: boolean, session?: string | null, roles?: string | null, workspace?: string | null }) => void
-  /** 同步 flush：写全部脏文件（dispose 最终落盘用）。 */
-  flushNow: () => void
   /** 删除群组/会话后摘除脏标记（对应文件已删/将删，flush 跳过）。 */
   dropDirty: (targets: { session?: string | null, roles?: string | null, workspace?: string | null }) => void
-  /** dispose：同步最终 flush → 释放锁 → 摘除句柄。 */
-  release: () => void
+  /** dispose：停止新调度 → 等待挂起 flush → 最终 flush → 释放锁（异步）。 */
+  release: () => Promise<void>
 }
 
 /**
@@ -56,12 +58,20 @@ export function createPersistence(core: HostState): Persistence {
   }
   const store = (): Store | null => core.store
 
-  // 脏标记按文件记；flush 失败者保留脏标记，下次触发自动重试
-  const dirtySessions = new Set<string>()
-  const dirtyRoles = new Set<string>()
-  const dirtyWorkspace = new Set<string>()
-  let ledgerDirty = false
+  // 脏标记按文件记（值 = 版本号，标记时递增）；flush 期间被重新标脏的文件
+  // 保留标记待下一轮 flush（写成功后版本未变才清除），失败同理自动重试
+  const dirtySessions = new Map<string, number>()
+  const dirtyRoles = new Map<string, number>()
+  const dirtyWorkspace = new Map<string, number>()
+  let ledgerDirty = 0
   let flushScheduled = false
+  // flush 串行链：writeFileAtomic 异步化后，防止并发 flush 对同一文件乱序
+  // rename（后写的旧内容盖住先写的新内容）；链上任务逐个排队执行
+  let flushChain: Promise<void> = Promise.resolve()
+
+  const mark = (map: Map<string, number>, key: string): void => {
+    map.set(key, (map.get(key) ?? 0) + 1)
+  }
 
   const ledgerDocument = (): LedgerDocument & { savedAt: number } => ({
     schema: 3,
@@ -85,57 +95,61 @@ export function createPersistence(core: HostState): Persistence {
   })
   const rolesDocument = (g: GroupRecord) => ({ schema: 1, savedAt: Date.now(), roles: g.roleIds.map((rid) => core.roles.get(rid)).filter((r): r is RoleRecord => Boolean(r)).map((r) => roleJson(r)) })
 
-  /** 同步 flush：写全部脏文件；成功才清脏标记；每个实际发生 rename 的目录一次 fsync。 */
-  const flushNow = (): void => {
-    const s = store()
-    if (s === null) return
+  /**
+   * 异步 flush（writeFileAtomic：wx 独占创建 + 随机后缀 tmp + rename，无
+   * per-file fsync——崩溃持久性对齐 DSH 基座标准）：写全部脏文件；写成功且
+   * 写入期间未被重新标脏（版本未变）才清脏标记；每个实际发生 rename 的
+   * 目录一次 fsync（调用侧批量执行）。
+   */
+  const flushAll = async (s: Store): Promise<void> => {
     const fsyncDirs = new Set<string>()
-    for (const sid of [...dirtySessions]) {
+    for (const [sid, v] of [...dirtySessions]) {
       const sess = core.sessions.get(sid)
       if (!sess) {
         dirtySessions.delete(sid)
         continue
       }
       try {
-        s.atomicWrite(s.sessionFile(sess.groupId, sess.id), JSON.stringify(sessionDocument(sess)))
-        dirtySessions.delete(sid)
+        await writeFileAtomic(s.sessionFile(sess.groupId, sess.id), JSON.stringify(sessionDocument(sess)), WRITE_FILE_OPTS)
+        if (dirtySessions.get(sid) === v) dirtySessions.delete(sid)
         fsyncDirs.add(s.sessionsDir(sess.groupId))
       } catch (e) {
         console.error(`[dsh-group-chat] 会话 ${sid} 落盘失败（保留脏标记待重试）：`, e)
       }
     }
-    for (const gid of [...dirtyRoles]) {
+    for (const [gid, v] of [...dirtyRoles]) {
       const g = core.groups.get(gid)
       if (!g) {
         dirtyRoles.delete(gid)
         continue
       }
       try {
-        s.atomicWrite(s.rolesFile(gid), JSON.stringify(rolesDocument(g)))
-        dirtyRoles.delete(gid)
+        await writeFileAtomic(s.rolesFile(gid), JSON.stringify(rolesDocument(g)), WRITE_FILE_OPTS)
+        if (dirtyRoles.get(gid) === v) dirtyRoles.delete(gid)
         fsyncDirs.add(s.groupDir(gid))
       } catch (e) {
         console.error(`[dsh-group-chat] 群组 ${gid} roles.json 落盘失败（保留脏标记待重试）：`, e)
       }
     }
-    for (const gid of [...dirtyWorkspace]) {
+    for (const [gid, v] of [...dirtyWorkspace]) {
       const g = core.groups.get(gid)
       if (!g) {
         dirtyWorkspace.delete(gid)
         continue
       }
       try {
-        s.atomicWrite(s.workspaceFile(gid), (g.workspaceDir || '') + '\n')
-        dirtyWorkspace.delete(gid)
+        await writeFileAtomic(s.workspaceFile(gid), (g.workspaceDir || '') + '\n', WRITE_FILE_OPTS)
+        if (dirtyWorkspace.get(gid) === v) dirtyWorkspace.delete(gid)
         fsyncDirs.add(s.groupDir(gid))
       } catch (e) {
         console.error(`[dsh-group-chat] 群组 ${gid} workspaceDir 落盘失败（保留脏标记待重试）：`, e)
       }
     }
-    if (ledgerDirty) {
+    if (ledgerDirty > 0) {
+      const v = ledgerDirty
       try {
-        s.atomicWrite(s.ledgerFile, JSON.stringify(ledgerDocument(), null, 2))
-        ledgerDirty = false
+        await writeFileAtomic(s.ledgerFile, JSON.stringify(ledgerDocument(), null, 2), WRITE_FILE_OPTS)
+        if (ledgerDirty === v) ledgerDirty = 0
         fsyncDirs.add(s.dir)
       } catch (e) {
         console.error('[dsh-group-chat] ledger.json 落盘失败（保留脏标记待重试）：', e)
@@ -147,15 +161,22 @@ export function createPersistence(core: HostState): Persistence {
   /** 事件驱动落盘；同一 tick 内多次变更合并为一次写。 */
   const schedulePersist = ({ ledger = false, session = null, roles: roleGroup = null, workspace = null }: { ledger?: boolean, session?: string | null, roles?: string | null, workspace?: string | null } = {}): void => {
     if (store() === null) return
-    if (ledger) ledgerDirty = true
-    if (session) dirtySessions.add(session)
-    if (roleGroup) dirtyRoles.add(roleGroup)
-    if (workspace) dirtyWorkspace.add(workspace)
+    if (ledger) ledgerDirty++
+    if (session) mark(dirtySessions, session)
+    if (roleGroup) mark(dirtyRoles, roleGroup)
+    if (workspace) mark(dirtyWorkspace, workspace)
     if (flushScheduled) return
     flushScheduled = true
     void Promise.resolve().then(() => {
       flushScheduled = false
-      flushNow()
+      // 排队进串行链；flushAll 按文件吞错（保留脏标记），此处兜底意外
+      // 逃逸的异常并把链复位为健康态，后续 flush 不被跳过
+      flushChain = flushChain.then(async () => {
+        const s = store()
+        if (s !== null) await flushAll(s)
+      }).catch((e) => {
+        console.error('[dsh-group-chat] 落盘 flush 异常（脏标记保留待重试）：', e)
+      })
     })
   }
 
@@ -311,18 +332,20 @@ export function createPersistence(core: HostState): Persistence {
 
   return {
     schedulePersist,
-    flushNow,
     dropDirty,
-    release(): void {
+    async release(): Promise<void> {
       const s = store()
       if (s === null) return
+      // 立即停止新调度并摘除句柄（后续 schedulePersist 直接 no-op）；
+      // 持有的 store 引用继续完成最终落盘
+      core.store = null
       try {
-        flushNow()
+        await flushChain
+        await flushAll(s)
       } catch {}
       try {
         s.release()
       } catch {}
-      core.store = null
     },
   }
 }

package/src/host/persistence/store.ts

@@ -126,7 +126,11 @@ export class Store {
     } catch {}
   }
 
-  /** 原子写：tmp+fsync+rename；目录 fsync 由调用方按 flush 批量执行（每目录一次）。 */
+  /**
+   * 同步原子写（tmp+fsync+rename）：仅供构造期 v1 迁移（migrateV1）与测试
+   * 直用；运行时 flush 走 persistence.ts 的 writeFileAtomic（异步、wx 独占
+   * 创建 + 随机后缀 + 符号链接安全，无 per-file fsync，对齐 DSH 基座标准）。
+   */
   atomicWrite(file: string, text: string): void {
     mkdirSync(dirname(file), { recursive: true })
     const tmp = `${file}.tmp-${process.pid}`

package/src/host/service.ts

@@ -28,8 +28,8 @@ export interface GroupChatService {
   subscribePush(push: () => void): () => void
   /** 设置停用时中止正在进行的群聊。 */
   stopAll(): void
-  /** 卸载/热重载：唤醒确认等待 + kill 子进程 → 同步最终 flush → 释放锁。 */
-  dispose(): void
+  /** 卸载/热重载：唤醒确认等待 + kill 子进程 → 异步最终 flush → 释放锁（cordis 会 await）。 */
+  dispose(): Promise<void>
 }
 
 /**
@@ -66,13 +66,13 @@ export function createGroupChatService(ctx: Context): GroupChatService {
         bus.touch()
       }
     },
-    dispose(): void {
+    dispose(): Promise<void> {
       core.run.stopping = true
       if (core.run.pendingConfirm) tools.wakeConfirm()
       tools.killChild()
       materials.disposeFileSearch()
       bus.dispose()
-      persist.release()
+      return persist.release()
     },
   }
 }

package/src/host/state.ts

@@ -8,9 +8,10 @@
 
 import { randomUUID } from 'node:crypto'
 import type { Context } from '@deepseek-ai/cordis'
-// 类型合并：ctx.llm / ctx.fs / ctx.workspaceRegistry（宿主面）
+// 类型合并：ctx.llm / ctx.fs / ctx.shell / ctx.workspaceRegistry（宿主面）
 import type {} from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-shell'
 import type {} from '@deepseek-ai/dsh-workspace'
 import type { Store } from './persistence/store.ts'
 import type { GroupRecord, LastCreated, MessageRecord, RoleRecord, RunState, SessionRecord } from '../core/types.ts'
@@ -36,6 +37,7 @@ export interface HostState {
   ctx: Context
   llm: Context['llm']
   fs: Context['fs']
+  shell: Context['shell']
   groups: Map<string, GroupRecord>
   sessions: Map<string, SessionRecord>
   roles: Map<string, RoleRecord>
@@ -59,11 +61,12 @@ export function createHostState(ctx: Context): HostState {
     ctx,
     llm: ctx.llm,
     fs: ctx.fs,
+    shell: ctx.shell,
     groups: new Map(),
     sessions: new Map(),
     roles: new Map(),
     messages: new Map(),
-    run: { running: false, sessionId: null, currentRoleId: null, partial: '', partialReasoning: '', stopping: false, queue: [], pendingConfirm: null, confirmSignal: null, childProc: null, finished: null, replaceMessageId: null },
+    run: { running: false, sessionId: null, currentRoleId: null, partial: '', partialReasoning: '', stopping: false, queue: [], pendingConfirm: null, confirmSignal: null, commandAbort: null, finished: null, replaceMessageId: null },
     store: null,
     revision: 1,
     idSeq: 1,

package/src/host/tools/tools.ts

@@ -1,15 +1,15 @@
 /**
  * 工具执行（TOOLS.md §2：沙箱 / §3：确认闸门）：read_file / list_dir /
  * run_command 三件套；realpath 硬边界 + 分隔符比较；run_command 按群组
- * 权限档位走逐条确认或直接执行。
+ * 权限档位走逐条确认或直接执行，经 `shell` 服务（ctx.shell 沙箱执行器）
+ * 以 per-call sandboxPolicy 收紧到群工作区。
  * @module dsh-group-chat/host/tools
  */
 
-import { spawn, type ChildProcess } from 'node:child_process'
 import { closeSync, openSync, readSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { isAbsolute, join, sep } from 'node:path'
 import { CMD_CAPTURE_MAX_BYTES, CMD_OUTPUT_MAX_CHARS, READ_FILE_MAX_BYTES, RUN_CMD_TIMEOUT_MS, TOOL_SCHEMAS } from '../../core/tools.ts'
-import type { GroupRecord, RunState, ToolExecution } from '../../core/types.ts'
+import type { GroupRecord, PendingConfirm, ToolExecution } from '../../core/types.ts'
 import type { HostState } from '../state.ts'
 
 /** 工具面。 */
@@ -28,7 +28,7 @@ export interface Tools {
 
 /** 创建工具面。 */
 export function createTools(core: HostState, touch: () => void): Tools {
-  const { run } = core
+  const { run, shell } = core
 
   /** realpath 硬边界：目标必须在群组工作区内（带分隔符比较，防 /ws/foo 放行 /ws/foobar）。 */
   const resolveInWorkspace = (root: string, rawPath: unknown): { ok: true, target: string } | { ok: false, error: string } => {
@@ -92,49 +92,44 @@ export function createTools(core: HostState, touch: () => void): Tools {
     }
   }
 
-  const runCommandTool = (root: string, command: string): Promise<{ status: 'ok' | 'error', output: string }> => new Promise((resolve) => {
-    let child: ChildProcess
+  /**
+   * 经 `shell` 服务执行命令（TOOLS.md §2）：cwd 与沙箱均收紧到群工作区根
+   * （workspace_write 档经 sandboxPolicy 强制；full_access 档对齐 DSH
+   * danger-full-access 语义免受限）。超时/中止由执行器 kill 进程并按首因
+   * 分类报告；runner 失效（如 SANDBOX_UNAVAILABLE）经 catch 报错不执行。
+   */
+  const runCommandTool = async (g: GroupRecord, root: string, command: string): Promise<{ status: 'ok' | 'error', output: string }> => {
+    const abort = new AbortController()
+    run.commandAbort = abort
     try {
-      child = spawn('bash', ['-c', command], { cwd: root })
+      const spec = shell.resolve({
+        command,
+        workdir: root,
+        timeoutMs: RUN_CMD_TIMEOUT_MS,
+        stdoutMaxBytes: CMD_CAPTURE_MAX_BYTES,
+        sandboxPolicy: g.permissionTier === 'full_access'
+          ? { mode: 'danger-full-access' as const, workspaceRoot: root }
+          : { mode: 'workspace-write' as const, workspaceRoot: root },
+        signal: abort.signal,
+      })
+      const r = await shell.run(spec)
+      let text = r.stdout.text + r.stderr.text
+      if (r.stdout.truncated || r.stderr.truncated) text += '\n[输出采集超限，已截断（保留末尾）]'
+      if (r.sandbox?.denied) text += '\n[沙箱拦截了越界的文件操作]'
+      if (r.timedOut) text += '\n[执行超时（' + Math.round(RUN_CMD_TIMEOUT_MS / 1000) + 's），已强制终止]'
+      if (r.exitCode !== 0 && r.exitCode !== null && !r.timedOut) text += '\n[退出码 ' + r.exitCode + ']'
+      if (text.length > CMD_OUTPUT_MAX_CHARS) text = text.slice(0, CMD_OUTPUT_MAX_CHARS) + '\n…(输出超长，已截断)'
+      return { status: r.exitCode === 0 ? 'ok' : 'error', output: text || '（无输出）' }
     } catch (e) {
-      resolve({ status: 'error', output: '无法启动命令：' + String((e && (e as Error).message) || e) })
-      return
-    }
-    run.childProc = child
-    let out = ''
-    let dropped = 0
-    let timedOut = false
-    const onChunk = (chunk: Buffer) => {
-      if (out.length < CMD_CAPTURE_MAX_BYTES) out += chunk.toString('utf8')
-      else dropped += chunk.length
-    }
-    child.stdout?.on('data', onChunk)
-    child.stderr?.on('data', onChunk)
-    const timer = setTimeout(() => {
-      timedOut = true
-      try {
-        child.kill('SIGKILL')
-      } catch {}
-    }, RUN_CMD_TIMEOUT_MS)
-    const finish = (result: { status: 'ok' | 'error', output: string }) => {
-      clearTimeout(timer)
-      if (run.childProc === child) run.childProc = null
-      resolve(result)
+      return { status: 'error', output: '无法启动命令：' + String((e && (e as Error).message) || e) }
+    } finally {
+      if (run.commandAbort === abort) run.commandAbort = null
     }
-    child.on('error', (e) => finish({ status: 'error', output: '执行失败：' + String((e && e.message) || e) }))
-    child.on('close', (code) => {
-      let text = out.length > CMD_CAPTURE_MAX_BYTES ? out.slice(0, CMD_CAPTURE_MAX_BYTES) : out
-      if (dropped > 0) text += '\n[输出采集超限，已丢弃 ' + dropped + ' 字节]'
-      if (timedOut) text += '\n[执行超时（' + Math.round(RUN_CMD_TIMEOUT_MS / 1000) + 's），已强制终止]'
-      if (code !== 0 && code !== null && !timedOut) text += '\n[退出码 ' + code + ']'
-      if (text.length > CMD_OUTPUT_MAX_CHARS) text = text.slice(0, CMD_OUTPUT_MAX_CHARS) + '\n…(输出超长，已截断)'
-      finish({ status: code === 0 ? 'ok' : 'error', output: text || '（无输出）' })
-    })
-  })
+  }
 
   /** run_command 确认闸门：置 pendingConfirm 后无限等待，confirmCommand/stop/dispose 唤醒。 */
   const requestConfirmation = (toolCallId: string, args: Record<string, unknown>): Promise<boolean> => new Promise((resolve) => {
-    run.pendingConfirm = { toolCallId, tool: 'run_command', args: args as RunState['pendingConfirm'] extends null ? never : NonNullable<RunState['pendingConfirm']>['args'] }
+    run.pendingConfirm = { toolCallId, tool: 'run_command', args: args as PendingConfirm['args'] }
     run.confirmSignal = { resolve }
     touch()
   })
@@ -151,11 +146,10 @@ export function createTools(core: HostState, touch: () => void): Tools {
   }
 
   const killChild = (): void => {
-    if (run.childProc) {
-      try {
-        run.childProc.kill('SIGKILL')
-      } catch {}
-    }
+    // 中止正在执行的命令：执行器收到 abort 信号后 kill 进程
+    try {
+      run.commandAbort?.abort()
+    } catch {}
   }
 
   const executeTool = async (g: GroupRecord, root: string, tc: { id: string, name: string, args: string }): Promise<ToolExecution> => {
@@ -175,9 +169,9 @@ export function createTools(core: HostState, touch: () => void): Tools {
         const allowed = await requestConfirmation(tc.id, args)
         if (run.stopping) res = { status: 'error', output: '对话已被用户停止，命令未执行' }
         else if (!allowed) res = { status: 'denied', output: '用户拒绝了这次命令执行' }
-        else res = await runCommandTool(root, String(args.command || ''))
+        else res = await runCommandTool(g, root, String(args.command || ''))
       } else {
-        res = await runCommandTool(root, String(args.command || ''))
+        res = await runCommandTool(g, root, String(args.command || ''))
       }
     } else {
       res = { status: 'error', output: '未知工具：' + tc.name }

package/src/index.ts

@@ -14,6 +14,9 @@
  *    （engine/fold.ts；立刻 idle、fire-and-forget，不产生消息）
  *  - 群组工作区目录经 `fs` 服务读取（根下一层文本文件，最多 20 个），
  *    以「共享资料」块注入每个角色的 system 提示词；无独立笔记/文件清单
+ *  - 工具执行（read_file/list_dir/run_command）见 docs/TOOLS.md：run_command
+ *    经 `shell` 服务（ctx.shell 沙箱执行器）执行，per-call sandboxPolicy
+ *    收紧到群工作区（workspace_write 档）或免受限（full_access 档）
  *  - 经 `webServer` 暴露 HTTP API：
  *      GET  /api/group-chat/state   全量快照
  *      POST /api/group-chat/action   { kind: mutate|send|stop|confirmCommand|models|efforts|browse|fileSearch, ... }
@@ -36,7 +39,7 @@ import { createGroupChatService, makeGroupChatRoutes } from './host/index.ts'
 
 export const name = 'group-chat'
 
-export const inject = ['llm', 'fs', 'webServer', 'workspaceRegistry']
+export const inject = ['llm', 'fs', 'shell', 'webServer', 'workspaceRegistry']
 
 /** 设置命名空间；浏览器半拼写同一值，两边不共享代码。 */
 export const SETTINGS_NAMESPACE = 'group-chat' as SettingsNamespace
@@ -65,10 +68,9 @@ export const apply = mountOnce('dsh-group-chat', (ctx: Context, config?: Config)
     }
   }, 'group-chat: host API routes')
 
-  // 插件卸载/热重载：唤醒确认等待 + kill 子进程 → 同步最终 flush → 释放锁
-  ctx.effect(() => () => {
-    service.dispose()
-  })
+  // 插件卸载/热重载：唤醒确认等待 + kill 子进程 → 异步最终 flush → 释放锁
+  // （返回 Promise，cordis 卸载时 await，保证新实例接管前锁已释放）
+  ctx.effect(() => () => service.dispose())
 
   // ---------- 设置（enabled 持久化于 settings.yaml） ----------
 

package/src/shared/file-mention-grammar.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, expect, it } from 'vitest'
-import { activeAtToken, formatFileMention } from './file-mention-grammar.ts'
+import { activeAtToken } from './file-mention-grammar.ts'
 
 describe('activeAtToken', () => {
   it('extracts plain @path at cursor', () => {
@@ -38,40 +38,3 @@ describe('activeAtToken', () => {
     expect(activeAtToken('\t@"test', 7)).toEqual({ prefix: '@"test', query: 'test', quoted: true })
   })
 })
-
-describe('formatFileMention', () => {
-  it('formats plain file without whitespace', () => {
-    expect(formatFileMention({ kind: 'file', path: 'README.md' }, false)).toBe('@README.md')
-    expect(formatFileMention({ kind: 'file', path: 'src/index.ts' }, false)).toBe('@src/index.ts')
-  })
-
-  it('formats plain directory with trailing slash', () => {
-    expect(formatFileMention({ kind: 'directory', path: 'src' }, false)).toBe('@src/')
-    expect(formatFileMention({ kind: 'directory', path: 'lib/utils' }, false)).toBe('@lib/utils/')
-  })
-
-  it('quotes file with whitespace and closes quote', () => {
-    expect(formatFileMention({ kind: 'file', path: 'My Document.txt' }, false)).toBe('@"My Document.txt"')
-    expect(formatFileMention({ kind: 'file', path: 'src/my file.ts' }, false)).toBe('@"src/my file.ts"')
-  })
-
-  it('quotes directory with whitespace but keeps quote open', () => {
-    expect(formatFileMention({ kind: 'directory', path: 'My Folder' }, false)).toBe('@"My Folder/')
-    expect(formatFileMention({ kind: 'directory', path: 'src/my lib' }, false)).toBe('@"src/my lib/')
-  })
-
-  it('preserves quote even when unnecessary', () => {
-    expect(formatFileMention({ kind: 'file', path: 'plain.txt' }, true)).toBe('@"plain.txt"')
-    expect(formatFileMention({ kind: 'directory', path: 'lib' }, true)).toBe('@"lib/')
-  })
-
-  it('rejects paths with control characters', () => {
-    expect(formatFileMention({ kind: 'file', path: 'file\x00.txt' }, false)).toBeUndefined()
-    expect(formatFileMention({ kind: 'file', path: 'file\n.txt' }, false)).toBeUndefined()
-  })
-
-  it('rejects paths with embedded quotes', () => {
-    expect(formatFileMention({ kind: 'file', path: 'file"name.txt' }, false)).toBeUndefined()
-    expect(formatFileMention({ kind: 'directory', path: 'dir"name' }, false)).toBeUndefined()
-  })
-})

package/src/shared/file-mention-grammar.ts

@@ -1,9 +1,12 @@
 /**
  * Vendored @file token grammar from dsh-file-reference (browser-safe, zero Node API).
- * 
+ *
  * Sourced from @deepseek-ai/dsh-file-reference/lib/types/grammar.js
  * Cannot import directly due to client bundle purity gate (dsh-client-bundle-purity).
- * 
+ *
+ * 只保留输入侧的 @token 识别（activeAtToken）；候选的文本化（formatFileMention）
+ * 未被本插件采用——目录钻入走「插入整颗芯片」语义，见 docs/DESIGN.md Composer 契约。
+ *
  * @module dsh-group-chat/shared
  */
 
@@ -16,22 +19,17 @@ export interface AtToken {
   quoted: boolean
 }
 
-export interface FileCandidate {
-  kind: 'file' | 'directory'
-  path: string
-}
-
 /**
  * Extract active @token at cursor position.
  * Matches @ at word boundary (line start or after whitespace).
- * 
+ *
  * @param line - Current line text
  * @param cursor - Cursor offset in line
  * @returns Token or undefined if no active @token at cursor
  */
 export function activeAtToken(line: string, cursor: number): AtToken | undefined {
   const before = line.slice(0, cursor)
-  
+
   // Try quoted @"... first (more specific)
   const quotedMatch = /(?:^|\s)@"([^"]*)$/.exec(before)
   if (quotedMatch) {
@@ -56,27 +54,3 @@ export function activeAtToken(line: string, cursor: number): AtToken | undefined
 
   return undefined
 }
-
-/**
- * Format file/directory candidate as @mention text.
- * 
- * @param candidate - File or directory to format
- * @param preserveQuote - Keep quotes even when unnecessary (for drill-down continuity)
- * @returns Formatted @path or undefined for invalid paths
- */
-export function formatFileMention(candidate: FileCandidate, preserveQuote: boolean): string | undefined {
-  const { path } = candidate
-
-  // Reject control characters and embedded quotes
-  if (/[\x00-\x1F"]/.test(path)) return undefined
-
-  const needsQuote = /\s/.test(path)
-  const useQuote = needsQuote || preserveQuote
-
-  if (candidate.kind === 'file') {
-    return useQuote ? `@"${path}"` : `@${path}`
-  } else {
-    // Directory: trailing slash, quote stays open for drill-down
-    return useQuote ? `@"${path}/` : `@${path}/`
-  }
-}

package/lib/types/client/Bubble.d.ts

@@ -1,10 +0,0 @@
-/**
- * 聊天消息气泡（user / system / 角色发言）。
- * @module dsh-group-chat/client/Bubble
- */
-import type { ReactNode } from 'react';
-import { type ClientSnapshot } from './model.ts';
-export declare function Bubble(props: {
-    snap: ClientSnapshot;
-    m: ClientSnapshot['messages'][number];
-}): ReactNode;

package/lib/types/client/Glyph.d.ts

@@ -1,12 +0,0 @@
-/**
- * 侧边栏入口图标。
- *
- * 整行命中层携带 “newSession” 类名：任务看板等 DOM 注入式面板用
- * [class*="newSession"] 识别“侧边栏导航点击”并自动收起自己，与点击
- * “新建会话”行为一致——类名不可哈希化。
- * @module dsh-group-chat/client/glyph
- */
-import type { ReactNode } from 'react';
-export declare function Glyph(props: {
-    size?: number;
-}): ReactNode;