@roaming-ai/dsh-group-chat 0.2.0

package/src/client/react-dom-shim.d.ts

@@ -0,0 +1,13 @@
+/** Platform modules (react-dom / client) have no @types in this plugin. */
+declare module 'react-dom' {
+  export function flushSync(fn: () => void): void
+}
+
+declare module 'react-dom/client' {
+  import type { ReactNode } from 'react'
+  export interface Root {
+    render(children: ReactNode): void
+    unmount(): void
+  }
+  export function createRoot(container: Element | DocumentFragment): Root
+}

package/src/client/utils/utils.ts

@@ -0,0 +1,104 @@
+/**
+ * 通用工具函数
+ * @module dsh-group-chat/client/utils
+ */
+
+import { createElement } from 'react'
+import { flushSync } from 'react-dom'
+import { createRoot } from 'react-dom/client'
+import { FileTypeIcon } from '@deepseek-ai/dsh-client-ui-primitives'
+import { activeAtToken, type AtToken } from '../../shared/file-mention-grammar.ts'
+
+/** HTML 转义（芯片以 execCommand('insertHTML') 注入，角色名需转义）。 */
+export function escapeHtml(v: string): string {
+  return String(v).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+/**
+ * execCommand 集中封装。它已被 Web 平台标记 @deprecated（ts 6387 编辑器提示），
+ * 但仍是唯一能让 contenteditable 的 DOM 编辑进入浏览器原生 undo 栈的同步 API
+ * （自研 undo 栈或引入 Lexical/ProseMirror 类框架代价更大；取舍见 DESIGN.md
+ * Composer 契约）。经中间别名擦除废弃标记，全部调用走本封装，不在调用处散布提示。
+ */
+type ExecCommandFn = (commandId: string, showUI?: boolean, value?: string) => boolean
+let execCommandFn: ExecCommandFn | undefined
+export function execCommand(commandId: 'delete' | 'insertHTML' | 'insertText' | 'insertLineBreak', value?: string): boolean {
+  execCommandFn ??= (document as unknown as { execCommand: ExecCommandFn }).execCommand
+  return execCommandFn.call(document, commandId, false, value)
+}
+
+/**
+ * contenteditable 输入区 → 纯文本序列化（发送/参与判定的唯一事实源）：
+ * 文本节点原样；<br> → 换行；角色芯片（.dsgc-chipin[data-role-id]）展开回「@名字␠」；
+ * 文件芯片（.dsgc-chipin[data-kind=file]）展开回「@path」或「@"path with spaces"」；
+ * DIV/P 块前补换行（防粘贴残留的块级包裹）。
+ */
+export function serializeInput(root: HTMLElement): string {
+  const walk = (node: Node): string => {
+    if (node.nodeType === Node.TEXT_NODE) return node.nodeValue || ''
+    if (node.nodeType !== Node.ELEMENT_NODE) return ''
+    const el = node as HTMLElement
+    if (el.tagName === 'BR') return '\n'
+    if (el.classList.contains('dsgc-chipin')) {
+      // 角色芯片
+      if (el.dataset.roleId) {
+        return '@' + (el.dataset.name || '') + ' '
+      }
+      // 文件芯片
+      if (el.dataset.kind === 'file') {
+        const path = el.dataset.path || ''
+        const needsQuote = /\s/.test(path)
+        return needsQuote ? `@"${path}"` : `@${path}`
+      }
+    }
+    const sep = /^(DIV|P)$/.test(el.tagName) ? '\n' : ''
+    return sep + Array.from(el.childNodes).map(walk).join('')
+  }
+  return Array.from(root.childNodes).map(walk).join('')
+}
+
+/** @角色芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+export function chipHtml(role: { id: string, name: string, color?: string }): string {
+  const c = escapeHtml(role.color || '#888')
+  return '<span class="dsgc-chipin" data-role-id="' + escapeHtml(role.id) + '" data-name="' + escapeHtml(role.name) + '" style="--role-color:' + c + '" contenteditable="false" draggable="true">' +
+    '<span class="dsgc-chipdot" style="background:' + c + '"></span>' + escapeHtml(role.name) + '</span>'
+}
+
+/** 把宿主 FileTypeIcon 渲成静态 SVG，再塞进 insertHTML（与检索列表同一套字形）。 */
+function fileTypeIconMarkup(path: string, kind: 'file' | 'directory'): string {
+  if (typeof document === 'undefined') return ''
+  const host = document.createElement('span')
+  const root = createRoot(host)
+  try {
+    flushSync(() => {
+      root.render(kind === 'directory'
+        ? createElement(FileTypeIcon, { kind: 'folder', size: 14 })
+        : createElement(FileTypeIcon, { path, size: 14 }))
+    })
+    return host.innerHTML
+  } finally {
+    root.unmount()
+  }
+}
+
+/** @文件芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+export function fileChipHtml(path: string, kind: 'file' | 'directory'): string {
+  const basename = path.split('/').pop() || path
+  const dir = kind === 'directory'
+  return '<span class="dsgc-chipin dsgc-chipin-file" data-kind="file"' + (dir ? ' data-dir="1"' : '') + ' data-path="' + escapeHtml(path) + '" contenteditable="false" draggable="true">' +
+    '<span class="dsgc-chipglyph" aria-hidden="true">' + fileTypeIconMarkup(path, kind) + '</span>' + escapeHtml(basename) + '</span>'
+}
+
+/**
+ * 光标前的活跃 @token（角色或文件弹层触发判定）。
+ * 
+ * @returns AtToken 对象，包含 prefix/query/quoted；无返回 null
+ */
+export function queryAtCaret(): AtToken | null {
+  const sel = window.getSelection()
+  if (!sel || !sel.isCollapsed || sel.rangeCount === 0) return null
+  const node = sel.anchorNode
+  if (!node || node.nodeType !== Node.TEXT_NODE) return null
+  const before = (node.nodeValue || '').slice(0, sel.anchorOffset)
+  return activeAtToken(before, before.length) || null
+}

package/src/core/json.ts

@@ -0,0 +1,28 @@
+/**
+ * 记录 → 落盘 JSON 的纯序列化（core 层；可选字段无则省略）。
+ * @module dsh-group-chat/core/json
+ */
+
+import type { MessageRecord, RoleRecord } from './types.ts'
+
+/** 消息 → 落盘 JSON（可选字段无则省略；兼容保留 error）。 */
+export function messageJson(m: Partial<MessageRecord> | undefined): Record<string, unknown> | null {
+  if (!m || typeof m.id !== 'string') return null
+  const o: Record<string, unknown> = { id: m.id, speaker: m.speaker, text: String(m.text || ''), ts: typeof m.ts === 'number' ? m.ts : Date.now(), seq: typeof m.seq === 'number' ? m.seq : 0 }
+  if (m.model !== undefined) o.model = m.model
+  if (m.reasoning !== undefined) o.reasoning = m.reasoning
+  if (m.reasoningFull !== undefined) o.reasoningFull = m.reasoningFull
+  if (m.thinkingSummary !== undefined) o.thinkingSummary = m.thinkingSummary
+  if (m.error !== undefined) o.error = m.error
+  if (Array.isArray(m.toolCalls) && m.toolCalls.length > 0) o.toolCalls = m.toolCalls
+  return o
+}
+
+/** 角色 → 落盘 JSON（groupId 由目录归属，不再写入）。 */
+export function roleJson(r: Partial<RoleRecord>): Record<string, unknown> {
+  const o: Record<string, unknown> = { id: r.id, name: String(r.name || '成员'), persona: String(r.persona || ''), provider: String(r.provider || ''), model: String(r.model || ''), enabled: r.enabled !== false, thinking: r.thinking === true }
+  if (r.color) o.color = r.color
+  if (typeof r.temperature === 'number' && !Number.isNaN(r.temperature)) o.temperature = r.temperature
+  if (typeof r.reasoningEffort === 'string' && r.reasoningEffort && r.reasoningEffort !== 'default') o.reasoningEffort = r.reasoningEffort
+  return o
+}

package/src/core/status.ts

@@ -0,0 +1,33 @@
+/**
+ * 会话状态派生（纯函数）：从快照 run 派生单个会话的列表状态，
+ * 语义对齐 DSH 主会话列表（StateDot 五态取四）。
+ *
+ * 优先级：等待确认 > 进行中 > 已完成/已出错 > 默认（无点）。
+ * - ongoing：run 进行中（含用户已点停止但未停完的 stopping 窗口）
+ * - warning：run_command 确认闸门挂起（仅工作区内修改档）
+ * - done/error：run 结束后的「输出完毕」标记（正常/停止 → done，发言失败 → error）
+ * - idle：无任何活动（不渲染状态点，对齐主 GUI idle 隐藏）
+ * @module dsh-group-chat/core/status
+ */
+
+import type { Snapshot } from './types.ts'
+
+/** 会话列表状态（取值即 StateDotState 的渲染态）。 */
+export type SessStatus = 'idle' | 'ongoing' | 'warning' | 'done' | 'error'
+
+/** 状态点悬停/读屏文案（idle 不渲染点，无文案）。 */
+export const SESS_STATUS_LABEL: Record<SessStatus, string> = {
+  idle: '',
+  ongoing: '进行中',
+  warning: '等待确认',
+  done: '已完成',
+  error: '已出错',
+}
+
+/** 派生单个会话的列表状态（run 为快照的 run 视图）。 */
+export function sessStatus(run: Snapshot['run'], sessionId: string): SessStatus {
+  if (run.running && run.sessionId === sessionId) return run.pendingConfirm ? 'warning' : 'ongoing'
+  const f = run.finished
+  if (f && f.sessionId === sessionId) return f.reason === 'error' ? 'error' : 'done'
+  return 'idle'
+}

package/src/core/tools.ts

@@ -0,0 +1,41 @@
+/**
+ * 工具执行护栏常量与 schema（TOOLS.md §1/§5；core 层纯数据）。
+ * @module dsh-group-chat/core/tools
+ */
+
+// ---------- 工具执行护栏常量（TOOLS.md §5） ----------
+/** run_command 超时。 */
+export const RUN_CMD_TIMEOUT_MS = 120e3
+/** read_file 单文件上限（超出截断）。 */
+export const READ_FILE_MAX_BYTES = 100 * 1024
+/** 单条工具输出回注截断。 */
+export const CMD_OUTPUT_MAX_CHARS = 8e3
+/** 命令输出采集内存上限（1MB，超出弃置仅计数）。 */
+export const CMD_CAPTURE_MAX_BYTES = 1 << 20
+/** 单条发言工具结果累计预算（含地板成本）。 */
+export const TOOL_RESULTS_TOTAL_MAX = 32e3
+/** 每次调用地板成本（防空输出零累积）。 */
+export const TOOL_FLOOR_COST_CHARS = 100
+/** 连续空输出/相同调用次数 → 强制收尾。 */
+export const TOOL_REPEAT_LIMIT = 6
+/** transcript 中工具输出摘要截断。 */
+export const TRANSCRIPT_TOOL_SUMMARY = 200
+
+/** 工具 schema（TOOLS.md §1）。 */
+export const TOOL_SCHEMAS = [
+  {
+    name: 'read_file',
+    description: '读取群组工作区目录内的一个文本文件内容（≤100KB，超出截断）',
+    parameters: { type: 'object', properties: { path: { type: 'string', description: '相对工作区根的路径' } }, required: ['path'] },
+  },
+  {
+    name: 'list_dir',
+    description: '列出群组工作区目录内一个子目录的条目（名称/类型/大小）',
+    parameters: { type: 'object', properties: { path: { type: 'string', description: '相对工作区根的路径，默认 "."' } } },
+  },
+  {
+    name: 'run_command',
+    description: '在群组工作区目录内执行 shell 命令（如运行测试、git 操作；超时 120 秒；是否需要确认取决于群组权限档位）',
+    parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+  },
+] as const

package/src/core/types.ts

@@ -0,0 +1,222 @@
+/**
+ * 群聊数据模型（core 层，无 cordis 依赖）。
+ * 数据模型：Group 1..N Session，消息挂在会话上；角色与工作区目录挂在群组上。
+ * @module dsh-group-chat/core/types
+ */
+
+/**
+ * 群组权限档位（对齐主会话 /permission 三档）：
+ * - view_only 仅可查看：只保留 read_file/list_dir，run_command 从 schema 剔除
+ * - workspace_write 工作区内修改：run_command 可用，每条命令逐条确认
+ * - full_access 完全权限：run_command 免确认直接执行
+ */
+export type PermissionTier = 'view_only' | 'workspace_write' | 'full_access'
+
+/** 全部合法档位（展示顺序）。 */
+export const PERMISSION_TIERS: readonly PermissionTier[] = ['view_only', 'workspace_write', 'full_access']
+
+/** 档位安全化：合法字符串原样，其余 undefined。 */
+export function asPermissionTier(value: unknown): PermissionTier | undefined {
+  return typeof value === 'string' && (PERMISSION_TIERS as readonly string[]).includes(value) ? value as PermissionTier : undefined
+}
+
+/**
+ * ledger 行档位归一（v2→v3 兼容）：显式 permissionTier 优先；
+ * 缺失时按旧布尔迁移——allowCommands=true → workspace_write（今日语义即
+ * 「可执行命令但逐条确认」），false/无字段 → view_only。
+ */
+export function migrateTier(permissionTier: unknown, allowCommands: unknown): PermissionTier {
+  const tier = asPermissionTier(permissionTier)
+  if (tier !== undefined) return tier
+  return allowCommands === true ? 'workspace_write' : 'view_only'
+}
+
+/** 群组：角色与工作区目录的宿主。 */
+export interface GroupRecord {
+  id: string
+  name: string
+  workspaceDir: string
+  permissionTier: PermissionTier
+  roleIds: string[]
+  sessionIds: string[]
+}
+
+/** 会话：消息挂在会话上。 */
+export interface SessionRecord {
+  id: string
+  groupId: string
+  name: string
+  topic: string
+  /** 名称已被手动编辑：自动命名永久跳过（隐式固定）。 */
+  namePinned?: boolean
+  /** 主题已被手动编辑：自动整理永久跳过（隐式固定）。 */
+  topicPinned?: boolean
+  messageIds: string[]
+  createdAt: number
+}
+
+/** 角色：绑定 provider/model 的群成员身份。 */
+export interface RoleRecord {
+  id: string
+  groupId: string
+  name: string
+  color?: string
+  persona: string
+  provider: string
+  model: string
+  temperature?: number
+  reasoningEffort?: string
+  enabled: boolean
+  thinking: boolean
+}
+
+/** 一次工具调用的落盘/快照形态（TOOLS.md §3.3 回注契约的展示面）。 */
+export interface ToolCallRecord {
+  tool: string
+  args: unknown
+  status: string
+  output: string
+  durationMs?: number
+}
+
+/** 消息（user / system / 角色发言共用一条记录）。 */
+export interface MessageRecord {
+  id: string
+  sessionId: string
+  seq: number
+  speaker: string
+  text: string
+  reasoning?: string
+  reasoningFull?: string
+  thinkingSummary?: string
+  model?: string
+  error?: boolean
+  toolCalls?: ToolCallRecord[]
+  ts: number
+}
+
+/** run_command 确认闸门的待确认载荷。 */
+export interface PendingConfirm {
+  toolCallId: string
+  tool: string
+  args: { command?: string } & Record<string, unknown>
+}
+
+/** 最近一次创建的群组/会话，供客户端定位选中项。 */
+export interface LastCreated {
+  kind: 'group' | 'session'
+  groupId: string
+  sessionId: string
+}
+
+/** run 结束后的「输出完毕」标记（内存态不持久化，重启即清；reason 取 ok/error）。 */
+export interface RunFinished {
+  sessionId: string
+  reason: 'ok' | 'error'
+}
+
+/** 对话进行时状态（run）。 */
+export interface RunState {
+  running: boolean
+  sessionId: string | null
+  currentRoleId: string | null
+  partial: string
+  partialReasoning: string
+  stopping: boolean
+  queue: string[]
+  pendingConfirm: PendingConfirm | null
+  confirmSignal: { resolve: (allowed: boolean) => void } | null
+  childProc: import('node:child_process').ChildProcess | null
+  /** 最近一次 run 的结束标记：会话列表「已完成/已出错」状态的数据源。 */
+  finished: RunFinished | null
+}
+
+/** 角色发言的引擎产物。 */
+export interface SpeakResult {
+  text: string
+  reasoning: string | undefined
+  toolCalls: ToolCallRecord[]
+}
+
+/** 工具执行结果（host 内部约定）。 */
+export interface ToolExecution {
+  status: 'ok' | 'error' | 'denied'
+  output: string
+  args: Record<string, unknown>
+  durationMs: number
+}
+
+/** 模型目录（models action 的缓存载荷）。 */
+export interface ModelCatalog {
+  at: number
+  providers: { id: string, name: string }[]
+  modelsByProvider: Record<string, { id: string, name?: string }[]>
+}
+
+/** 推理级别选项（efforts action 的载荷）。 */
+export interface EffortOptions {
+  efforts: { id: string, name: string, description?: string }[]
+  defaultEffort: string | undefined
+  error?: string
+}
+
+/** 目录浏览结果（browse action 的载荷）。 */
+export interface BrowseResult {
+  ok: boolean
+  path?: string
+  home?: string
+  parent?: string
+  entries?: { name: string, type: string, path: string, size?: number, hidden: boolean }[]
+  error?: string
+}
+
+/** 群工作区 @ 文件检索结果（fileSearch action 的载荷）。 */
+export interface FileSearchResult {
+  ok: boolean
+  candidates?: { path: string, isDir: boolean }[]
+  error?: string
+}
+
+/** 发到客户端的全量快照（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 }
+  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, 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, toolCalls?: ToolCallRecord[], ts: number }[]
+  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
+}
+
+/** send 动作的参数形态。 */
+export interface SendArgs {
+  sessionId: string
+  text?: string
+  participantRoleIds?: string[]
+  rounds?: number
+}
+
+/** 可选数值参数安全化：数字则原样，否则 undefined。 */
+export function asNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && !Number.isNaN(value) ? value : undefined
+}
+
+/** 可选字符串参数安全化：非 default 的非空字符串则原样，否则 undefined。 */
+export function asEffort(value: unknown): string | undefined {
+  return typeof value === 'string' && value && value !== 'default' ? value : undefined
+}