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

package/src/core/types.ts

@@ -202,31 +202,39 @@ export interface FileSearchResult {
   error?: string
 }
 
-/** 发到客户端的全量快照（wire 形态）。 */
+/** 快照内的会话行（wire 形态：不含 hydrate 用的固定标记与折入水位）。 */
+export type SnapshotSession = Omit<SessionRecord, 'namePinned' | 'topicPinned' | 'constraintsUpToSeq'>
+/** 快照内的消息行（wire 形态：思考全文与摘要不外发）。 */
+export type SnapshotMessage = Omit<MessageRecord, 'reasoningFull' | 'thinkingSummary'>
+
+/** 发到客户端的全量快照（wire 形态；各表行由领域记录派生，字段增删由编译器同步）。 */
 export interface Snapshot {
   revision: number
-  run: { running: boolean, sessionId: string | null, currentRoleId: string | null, partial: string, partialReasoning: string, pendingConfirm: PendingConfirm | null, finished: RunFinished | null, replaceMessageId: string | null }
+  run: Omit<RunState, 'stopping' | 'queue' | 'confirmSignal' | 'childProc'>
   lastCreated: LastCreated | null
-  groups: { id: string, name: string, workspaceDir: string, permissionTier: PermissionTier, roleIds: string[], sessionIds: string[] }[]
-  sessions: { id: string, groupId: string, name: string, topic: string, constraints?: SessionConstraint[], messageIds: string[], createdAt: number }[]
-  roles: { id: string, groupId: string, name: string, color?: string, persona: string, provider: string, model: string, temperature?: number, reasoningEffort?: string, enabled: boolean, thinking: boolean }[]
-  messages: { id: string, sessionId: string, seq: number, speaker: string, text: string, reasoning?: string, model?: string, error?: boolean, failedRoleId?: string, toolCalls?: ToolCallRecord[], ts: number }[]
+  groups: GroupRecord[]
+  sessions: SnapshotSession[]
+  roles: RoleRecord[]
+  messages: SnapshotMessage[]
   error?: string
 }
 
-/** mutate 动作的参数形态（op 分发见 host/service）。 */
-export interface MutateArgs {
-  op: string
-  groupId?: string
-  sessionId?: string
-  roleId?: string
-  role?: Partial<RoleRecord>
-  name?: string
-  topic?: string
-  path?: string
-  tier?: string
-  enabled?: boolean
-}
+/** mutate 动作的参数形态（判别联合：按 op 收窄各分支字段；wire 上字段可缺，消费方各自守卫）。 */
+export type MutateArgs =
+  | { op: 'createGroup', name?: string }
+  | { op: 'renameGroup', groupId: string, name?: string }
+  | { op: 'deleteGroup', groupId: string }
+  | { op: 'createSession', groupId: string, name?: string }
+  | { op: 'renameSession', sessionId: string, name?: string }
+  | { op: 'deleteSession', sessionId: string }
+  | { op: 'setTopic', sessionId: string, topic?: string }
+  | { op: 'upsertRole', groupId: string, role?: Partial<RoleRecord> }
+  | { op: 'deleteRole', roleId: string }
+  | { op: 'setRoleEnabled', roleId: string, enabled?: boolean }
+  | { op: 'setWorkspaceDir', groupId: string, path?: string }
+  | { op: 'setPermissionTier', groupId: string, tier?: string }
+  | { op: 'ackFinish' }
+  | { op: 'clearMessages', sessionId: string }
 
 /** send 动作的参数形态。 */
 export interface SendArgs {

package/src/host/api/actions.ts

@@ -36,7 +36,8 @@ export function createActions(core: HostState, deps: {
   const { touch, snapshot, schedulePersist, dropDirty, appendMessage, runLoop, wakeConfirm, killChild, browse, fileSearch, disposeFileSearch } = deps
 
   const mutate = (args: MutateArgs): Snapshot => {
-    const op = args && args.op
+    // 直接属性别名保持判别联合收窄（调用方 handleAction 已保证 body 为对象）
+    const op = args.op
     if (op === 'createGroup') {
       const g: GroupRecord = { id: core.nid('grp'), name: String(args.name || '').trim() || '群组 ' + (groups.size + 1), workspaceDir: '', permissionTier: 'view_only', roleIds: [], sessionIds: [] }
       groups.set(g.id, g)
@@ -46,14 +47,14 @@ export function createActions(core: HostState, deps: {
       schedulePersist({ ledger: true, session: sess.id })
       touch()
     } else if (op === 'renameGroup') {
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       if (g && String(args.name || '').trim()) {
         g.name = String(args.name).trim()
         schedulePersist({ ledger: true })
         touch()
       }
     } else if (op === 'deleteGroup') {
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       if (!g) return { ...snapshot(), error: '群组不存在' }
       if (groups.size <= 1) return { ...snapshot(), error: '至少保留一个群组' }
       if (run.running) {
@@ -80,7 +81,7 @@ export function createActions(core: HostState, deps: {
       schedulePersist({ ledger: true })
       touch()
     } else if (op === 'createSession') {
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       if (!g) return { ...snapshot(), error: '群组不存在' }
       const sess = core.newSession(g.id, String(args.name || '').trim() || undefined)
       g.sessionIds.push(sess.id)
@@ -88,7 +89,7 @@ export function createActions(core: HostState, deps: {
       schedulePersist({ ledger: true, session: sess.id })
       touch()
     } else if (op === 'renameSession') {
-      const sess = sessions.get(args.sessionId!)
+      const sess = sessions.get(args.sessionId)
       if (sess && String(args.name || '').trim()) {
         sess.name = String(args.name).trim()
         sess.namePinned = true // 手动编辑 = 隐式固定：自动命名此后跳过名称
@@ -96,7 +97,7 @@ export function createActions(core: HostState, deps: {
         touch()
       }
     } else if (op === 'deleteSession') {
-      const sess = sessions.get(args.sessionId!)
+      const sess = sessions.get(args.sessionId)
       if (!sess) return { ...snapshot(), error: '会话不存在' }
       const g = groups.get(sess.groupId)
       if (g && g.sessionIds.length <= 1) return { ...snapshot(), error: '每个群组至少保留一个会话' }
@@ -115,7 +116,7 @@ export function createActions(core: HostState, deps: {
       schedulePersist({ ledger: true })
       touch()
     } else if (op === 'setTopic') {
-      const sess = sessions.get(args.sessionId!)
+      const sess = sessions.get(args.sessionId)
       if (sess) {
         sess.topic = String(args.topic || '')
         sess.topicPinned = true // 手动编辑 = 隐式固定：自动整理此后跳过主题
@@ -123,7 +124,7 @@ export function createActions(core: HostState, deps: {
         touch()
       }
     } else if (op === 'upsertRole') {
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       const r = args.role || {}
       if (!g) return { ...snapshot(), error: '群组不存在' }
       if (!r.name || !String(r.name).trim()) return { ...snapshot(), error: '角色名称不能为空' }
@@ -161,7 +162,7 @@ export function createActions(core: HostState, deps: {
         touch()
       }
     } else if (op === 'deleteRole') {
-      const r = roles.get(args.roleId!)
+      const r = roles.get(args.roleId)
       if (r) {
         const gid = r.groupId
         const g = groups.get(gid)
@@ -171,14 +172,14 @@ export function createActions(core: HostState, deps: {
         touch()
       }
     } else if (op === 'setRoleEnabled') {
-      const r = roles.get(args.roleId!)
+      const r = roles.get(args.roleId)
       if (r) {
         r.enabled = !!args.enabled
         schedulePersist({ roles: r.groupId })
         touch()
       }
     } else if (op === 'setWorkspaceDir') {
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       if (g) {
         g.workspaceDir = String(args.path || '').trim()
         schedulePersist({ workspace: g.id })
@@ -187,7 +188,7 @@ export function createActions(core: HostState, deps: {
     } else if (op === 'setPermissionTier') {
       const tier = asPermissionTier(args.tier)
       if (!tier) return { ...snapshot(), error: '未知权限档位' }
-      const g = groups.get(args.groupId!)
+      const g = groups.get(args.groupId)
       if (g) {
         g.permissionTier = tier
         // 降到仅可查看时若该群挂着待确认命令，自动拒绝（安全侧倾斜）；
@@ -206,7 +207,7 @@ export function createActions(core: HostState, deps: {
         touch()
       }
     } else if (op === 'clearMessages') {
-      const sess = sessions.get(args.sessionId!)
+      const sess = sessions.get(args.sessionId)
       if (sess) {
         if (run.running && run.sessionId === sess.id) return { ...snapshot(), error: '对话进行中，无法清空' }
         for (const mid of sess.messageIds) messages.delete(mid)

package/src/host/engine/conversation.ts

@@ -6,12 +6,13 @@
 
 import { realpathSync } from 'node:fs'
 import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
-import { constraintBlock, formatTranscriptLine, prefixIds, speakerLabel, squeezedMessages, tempTranscript, WINDOW_SIZE } from '../../core/constraints.ts'
+import { constraintBlock, formatTranscriptLine, prefixIds, squeezedMessages, tempTranscript, WINDOW_SIZE } from '../../core/constraints.ts'
 import { unwrapSpeakFailure } from '../../core/errors.ts'
 import { TOOL_FLOOR_COST_CHARS, TOOL_REPEAT_LIMIT, TOOL_RESULTS_TOTAL_MAX, TRANSCRIPT_TOOL_SUMMARY } from '../../core/tools.ts'
 import type { GroupRecord, MessageRecord, RoleRecord, SessionRecord, SpeakResult, ToolCallRecord } from '../../core/types.ts'
 import { asEffort } from '../../core/types.ts'
 import type { HostState } from '../state.ts'
+import { speakerNameOf } from './defaults.ts'
 import { createFold } from './fold.ts'
 import { createRetitle } from './retitle.ts'
 import type { Materials } from '../materials/index.ts'
@@ -44,7 +45,6 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
   // 标题/主题自动整理 + 窗口外约束折叠（finally 之后并列后台跑，不占用 run）
   const retitle = createRetitle(core, { touch, schedulePersist })
   const fold = createFold(core, { touch, schedulePersist })
-  const nameOf = (speaker: string): string => speakerLabel(speaker, (roles.get(speaker) || { name: undefined }).name)
 
   const appendMessage = (sess: SessionRecord, speaker: string, text: string, extra?: Partial<MessageRecord>): MessageRecord => {
     const msg: MessageRecord = { id: core.nid('msg'), sessionId: sess.id, seq: sess.messageIds.length + 1, speaker, text, reasoning: undefined, model: undefined, error: undefined, ts: Date.now() }
@@ -64,57 +64,50 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
     return msg
   }
 
+  /** 原地覆盖既有消息（重试槽位）；目标不存在或不属于本会话时返回 false，由调用方走追加。 */
+  const overwriteMessage = (sess: SessionRecord, replaceId: string | undefined, patch: Partial<MessageRecord>): boolean => {
+    if (!replaceId) return false
+    const existing = messages.get(replaceId)
+    if (!existing || existing.sessionId !== sess.id) return false
+    Object.assign(existing, patch, { ts: Date.now() })
+    touch()
+    schedulePersist({ session: sess.id })
+    return true
+  }
+
   /** 把失败回合写成该角色的消息（speaker = 角色 id），不再用系统胶囊顶替。 */
   const writeFailure = (sess: SessionRecord, role: RoleRecord, err: unknown, replaceId?: string): void => {
     const raw = unwrapSpeakFailure(String((err && (err as Error).message) || err))
-    const extra: Partial<MessageRecord> = {
-      error: true,
-      failedRoleId: role.id,
-      model: role.provider + ' / ' + role.model,
-    }
-    if (replaceId) {
-      const existing = messages.get(replaceId)
-      if (existing && existing.sessionId === sess.id) {
-        existing.speaker = role.id
-        existing.text = raw
-        existing.error = true
-        existing.failedRoleId = role.id
-        existing.model = extra.model
-        existing.reasoning = undefined
-        existing.reasoningFull = undefined
-        existing.thinkingSummary = undefined
-        existing.toolCalls = undefined
-        existing.ts = Date.now()
-        touch()
-        schedulePersist({ session: sess.id })
-        return
-      }
-    }
+    const model = role.provider + ' / ' + role.model
+    const extra: Partial<MessageRecord> = { error: true, failedRoleId: role.id, model }
+    if (overwriteMessage(sess, replaceId, {
+      speaker: role.id,
+      text: raw,
+      ...extra,
+      reasoning: undefined,
+      reasoningFull: undefined,
+      thinkingSummary: undefined,
+      toolCalls: undefined,
+    })) return
     appendMessage(sess, role.id, raw, extra)
   }
 
   /** 成功发言写入：replaceId 存在则原地覆盖失败卡。 */
   const writeSuccess = (sess: SessionRecord, role: RoleRecord, out: SpeakResult, replaceId?: string): void => {
-    const extra: Partial<MessageRecord> = { model: role.provider + ' / ' + role.model, reasoning: out.reasoning, toolCalls: out.toolCalls }
-    if (replaceId) {
-      const existing = messages.get(replaceId)
-      if (existing && existing.sessionId === sess.id) {
-        existing.speaker = role.id
-        existing.text = out.text
-        existing.error = undefined
-        existing.failedRoleId = undefined
-        existing.model = extra.model
-        existing.reasoning = out.reasoning
-        existing.reasoningFull = undefined
-        existing.thinkingSummary = undefined
-        existing.toolCalls = Array.isArray(out.toolCalls) && out.toolCalls.length > 0 ? out.toolCalls : undefined
-        existing.ts = Date.now()
-        touch()
-        schedulePersist({ session: sess.id })
-        return
-      }
-    }
-    appendMessage(sess, role.id, out.text, extra)
+    const model = role.provider + ' / ' + role.model
+    const toolCalls = Array.isArray(out.toolCalls) && out.toolCalls.length > 0 ? out.toolCalls : undefined
+    if (overwriteMessage(sess, replaceId, {
+      speaker: role.id,
+      text: out.text,
+      error: undefined,
+      failedRoleId: undefined,
+      model,
+      reasoning: out.reasoning,
+      reasoningFull: undefined,
+      thinkingSummary: undefined,
+      toolCalls,
+    })) return
+    appendMessage(sess, role.id, out.text, { model, reasoning: out.reasoning, toolCalls: out.toolCalls })
   }
 
   /** 群聊记录 → 角色上下文块（最近 40 条 + 未折入临时原文）。失败卡不进上下文。重试截到该条之前。 */
@@ -123,10 +116,10 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
     for (const mid of prefixIds(sess.messageIds, skipId).slice(-WINDOW_SIZE)) {
       const m = messages.get(mid)
       if (!m || m.id === skipId || m.error) continue
-      out.push(formatTranscriptLine(m, nameOf(m.speaker)))
+      out.push(formatTranscriptLine(m, speakerNameOf(roles, m.speaker)))
     }
     const live = out.join('\n\n')
-    const temp = tempTranscript(squeezedMessages(messages, sess, skipId), (m) => nameOf(m.speaker))
+    const temp = tempTranscript(squeezedMessages(messages, sess, skipId), (m) => speakerNameOf(roles, m.speaker))
     if (!temp) return live
     if (!live) return temp
     return temp + '\n\n' + live
@@ -297,7 +290,10 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
       msgs.push({ id: ('g' + core.revision + '-a' + msgs.length) as Message['id'], role: 'assistant', content: assistantContent, source: { kind: 'model', provider: role.provider, model: role.model } })
       for (const tc of round.tcs) {
         if (run.stopping) break
-        const res = await tools.executeTool(g, wsRoot!, tc)
+        // wsRoot 为 null 时 toolSchemas 必为空、不会产生 tool-call；防御性跳出，
+        // 不把空根传进沙箱
+        if (wsRoot === null) break
+        const res = await tools.executeTool(g, wsRoot, tc)
         const output = String(res.output || '')
         toolCalls.push({ tool: tc.name, args: res.args, status: res.status, output, durationMs: res.durationMs })
         budgetUsed += Math.max(output.length, TOOL_FLOOR_COST_CHARS)
@@ -326,12 +322,15 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
   }
 
   const runLoop = async (sess: SessionRecord, opts?: { replaceMessageId?: string }): Promise<void> => {
-    const g = groups.get(sess.groupId)
+    const g = groups.get(sess.groupId) ?? null
     const startCount = sess.messageIds.length
     let failed = false // 发言失败 → 会话列表「已出错」标记
     let replaceId = opts && opts.replaceMessageId
     run.replaceMessageId = replaceId || null
     try {
+      // 群组在 run 期间不可删（send 已校验 + deleteGroup 拦截运行中群组）；
+      // 防御性早退——置空让 finally 走统一复位路径
+      if (!g) return
       while (run.queue.length > 0 && !run.stopping) {
         const roleId = run.queue.shift()!
         const role = roles.get(roleId)
@@ -343,7 +342,7 @@ export function createConversation(core: HostState, deps: { touch: () => void, s
         const targetId = replaceId
         replaceId = undefined
         try {
-          const out = await speak(g!, sess, role, targetId)
+          const out = await speak(g, sess, role, targetId)
           // 停止后不落部分消息（已有「已停止本次对话」系统消息承接）
           if (!run.stopping && (out.text || (Array.isArray(out.toolCalls) && out.toolCalls.length > 0))) {
             writeSuccess(sess, role, out, targetId)

package/src/host/engine/defaults.ts

@@ -0,0 +1,28 @@
+/**
+ * 引擎共享小件：DSH 默认模型读取 + 发言人展示名（retitle / fold / conversation 共用）。
+ * @module dsh-group-chat/host/engine/defaults
+ */
+
+import { speakerLabel } from '../../core/constraints.ts'
+import type { RoleRecord } from '../../core/types.ts'
+import type { HostState } from '../state.ts'
+
+/** DSH 默认模型（agentDefaultModel 服务缺位或未配置时返回 null，调用方静默跳过）。 */
+export 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
+  }
+}
+
+/** 发言人展示名（roles 表内查角色名；user/system 固定文案，见 speakerLabel）。 */
+export const speakerNameOf = (roles: Map<string, RoleRecord>, speaker: string): string =>
+  speakerLabel(speaker, roles.get(speaker)?.name)

package/src/host/engine/fold.ts

@@ -13,24 +13,11 @@ import {
   parseConstraints,
   squeezedMaxSeq,
   squeezedMessages,
-  speakerLabel,
   takeFoldBatch,
 } from '../../core/constraints.ts'
 import type { SessionRecord } from '../../core/types.ts'
 import type { HostState } from '../state.ts'
-
-/** DSH 默认模型（与 retitle 同一读取面；缺位返回 null）。 */
-const defaultModel = (core: HostState): { provider: string, model: string } | null => {
-  try {
-    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
-  }
-}
+import { defaultModel, speakerNameOf } from './defaults.ts'
 
 /**
  * 每轮 send 结束后折叠窗口外约束：fire-and-forget、不产生消息、静默失败。
@@ -41,13 +28,11 @@ export function createFold(core: HostState, deps: { touch: () => void, scheduleP
   const { touch, schedulePersist } = deps
   const folding = new Set<string>()
 
-  const nameOf = (speaker: string): string => speakerLabel(speaker, (roles.get(speaker) || { name: undefined }).name)
-
   return async (sess: SessionRecord): Promise<void> => {
     if (folding.has(sess.id)) return
     const squeezed = squeezedMessages(messages, sess)
     if (!squeezed.length) return
-    const input = takeFoldBatch(squeezed, (m) => nameOf(m.speaker))
+    const input = takeFoldBatch(squeezed, (m) => speakerNameOf(roles, m.speaker))
     const watermark = squeezedMaxSeq(input.consumed)
     if (watermark <= 0) return
 

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/tools/tools.ts

@@ -9,7 +9,7 @@ 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'
 
 /** 工具面。 */
@@ -134,7 +134,7 @@ export function createTools(core: HostState, touch: () => void): Tools {
 
   /** 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()
   })

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;