多 AI 群聊Qx002/dsh-group-chat

dsh-group-chat

DSH 原生多 AI 群聊插件：用户作为「群主」，在 DSH WebUI 中管理一组可配置的 AI
角色，让它们围绕共享上下文进行多模型轮流发言。纯 Node.js / Cordis 实现，
不使用 Tauri / Rust。

仓库主页:  -->

阶段状态

| 阶段 | 内容 | 状态 |
| --- | --- | --- |
| 阶段 1 | 基础设施：包清单、核心接口、Cordis 注册与 ctx.groupChat Service 暴露 | ✅ 已完成 |
| 阶段 2 | 编排器引擎：消息拦截、多模型轮流生成、主动/被动发言、共享上下文 | ✅ 已完成 |
| 阶段 3 | WebUI：输入框旁群聊开关 + 群聊设置页（React + slot 注入） | ✅ 已完成（本仓库当前状态） |

架构

src/
├── index.ts       插件入口（class plugin）：name / Config / 默认导出 GroupChatService
├── service.ts     GroupChatService (extends Service)：暴露 ctx.groupChat（配置注册 + 轮次门面 + API 挂载 + 模型目录 + 消息视图）
├── orchestrator.ts GroupChatEngine：独立群聊页的消息通道、轮次循环、主动发言调度（阶段 2 核心）
├── api.ts         主机端 WebUI API 路由（/api/group-chat/，webServer 注册）
├── context.ts     共享上下文构建：[AI名称]:  转写 + system prompt 协议（纯函数）
├── speakers.ts    群主规则 → 发言者选择（提及/触发/主动/默认，禁言跳过）（纯函数）
├── config.ts      DEFAULTS（唯一权威默认值）+ schemastery schema + assertGroupConfig 校验
├── error.ts       GroupChatError（稳定机器码）
├── types.ts       纯类型契约：GroupConfig / AgentConfig / HostRules / 轮次结果 / 模型目录 / 消息气泡类型
└── client/        WebUI（React，经 tsdown 打包为 lib/client.js）
├── index.ts                   客户端插件入口：apply(ctx) 注册 slot
├── api.ts                     类型化 fetch 客户端（镜像主机路由）
├── GroupChatToggle.tsx        群聊开关（conversation.input.left）：开/关独立群聊页面
├── GroupChatOverlay.tsx       群聊页面容器（约 2/3 居中，右上 ✕ 关闭，左上 ⚙ 设置）
├── GroupChatChatView.tsx      微信式聊天视图（AI 左 / 用户右气泡，文本+图片发送，轮询）
├── ModelPicker.tsx            Model ID 级联选择器（提供方 → 模型，同步 DSH 模型目录）
├── GroupChatSettingsPanel.tsx 设置面板内容（角色管理/群主规则/共享上下文/用户名称显示）
├── GroupChatSettingsSection.tsx 设置面板中的“群聊设置”页（settings.section）
└── styles.ts                  共享内联样式
build/           tsdown 客户端打包预设（平台 externals + 纯净化 gate + __ModuleLoader__ 交接）

阶段 3：WebUI（slot 注入 + 独立群聊页）

浏览器端是一个标准 DSH 客户端插件：lib/client.js 通过
window.__ModuleLoader__.load({id, factory}) 交接（与官方 dsh-web-ui 管线一致），
factory 导出 apply(ctx) / name / inject，收到客户端 cordis 根上下文。

产品形态：群聊是独立页面，与工作区原生对话完全隔离（原生输入框/模型选择/
读写权限等继续为工作流服务，群聊不接管、不混淆）：

| Slot | 内容 |
| --- | --- |
| conversation.input.left | 输入卡工具栏左端的群聊开关：点击开启/关闭独立群聊页面（状态点 + 开/关，持久化到 enabledSessions，全局开关自动联动） |
| settings.section (id group-chat) | 设置面板导航中的群聊设置页（GroupChatSettingsPanel） |

独立群聊页面（GroupChatOverlay，约覆盖原生对话区域 2/3、居中）：
- 左上角 ⚙ 切换群聊设置（同一面板）；右上角 ✕ 关闭页面 —— 关闭后
输入框旁的群聊开关同步回到“关”（enabledSessions 移除，主动发言定时器停止）；
- 聊天视图（GroupChatChatView，微信式布局）：AI 成员消息在左、用户在右，
气泡上方显示名称、下方显示内容；独立输入框支持 Enter 发送、Shift+Enter 换行、
发送图片（PNG/JPEG/WebP/GIF，经 DSH attachment 服务持久化后作为 image block
进入模型请求并在气泡内显示）；页面打开期间轮询消息视图；
- 用户侧名称来自群聊设置里的 用户名称显示（GroupConfig.userName，身份默认
“群主”），同时作为共享上下文转写中用户行的前缀。

群聊设置页包含：
- 群聊状态：全局开关、群聊名称、用户名称显示；
- AI 角色管理：成员列表（名称、模型、主动/被动、禁言徽标）、添加/编辑（角色卡
System Prompt、初始上下文、Provider/Model、发言模式、主动发言策略、@别名、
触发词、禁言/启用权限）、删除、快捷禁言；
- 模型 ID 级联选择器（ModelPicker）：点击后先列出 DSH 已接入的模型提供方
（ctx.llm.listProviders()），点击提供方再列出该提供方通告的模型
（listModels(provider)）—— 与 DSH 模型接入/模型选择 UI 的数据完全一致；
无目录或需要手填时保留 provider/model 手动输入；
- 群主规则：禁言全体、主动发言总开关、单轮回复上限、单轮发言者上限、并行生成、
超时、@ 语法；
- 共享上下文：转写窗口、转写模板、角色卡注入开关。

数据通道：浏览器 fetch → 主机 ctx.webServer 路由（src/api.ts，
同源 POST 防护，错误统一 {ok:false, code, message}）→ ctx.groupChat 门面
→ 编排器/配置存储。客户端 src/client/api.ts 提供类型化封装并把非 ok 响应
转为 GroupChatClientError。

构建：npm run build = tsc（主机 lib）+ tsdown（浏览器 client.js）。
客户端 bundle 只允许：平台模块（react、cordis、ui-slots 等，运行时由 shell 的
模块表解析）与内联安全层；任何其他 @deepseek-ai 值导入会被 build 期纯度
gate 拒绝（跨插件协作必须走 cordis 服务）。

阶段 2：编排器引擎

1. 消息通道

群聊是独立页面，所有消息都走显式通道：
ctx.groupChat.submitMessage(sessionId, text, images?) —— 独立群聊页的输入框
调用；创建 user/message 事件（可含 image block）、运行群聊轮次。要求群聊已
启用且该会话在 enabledSessions 中。原生工作区输入框不会被接管（不再注册
agent/pre-step 拦截），群聊与工作流对话完全隔离。

2. 发言者选择（selectSpeakers，依据 HostRules）

候选池 = agents.filter(enabled && !muted)        # 禁言/移除直接跳过
优先级：mentioned（@名字/别名）→ triggered（触发词）→ active（主动发言成员）
→ default（无人触发时由第一个可用成员兜底）
截断：maxAgentsPerTurn；muteAll → 不生成（但用户消息仍落盘）

3. 共享上下文（统一 Session Log，context.ts）

- 每个发言者看到同一份转写：session.deriveMessages() 投影为
[AI名称]:  行（宿主行使用群聊设置里的 用户名称显示，默认 群主），
按 sharedContext.transcriptTemplate 渲染，滚动窗口 maxMessages 行。
- system prompt = 角色卡（systemPrompt）+ 群聊协议（回复模式或主动发言模式），
协议在最后（最近的指令权重最高）。
- 顺序模式下，后发言者能看到本轮先发言者的最新回复（每步重新派生转写）。

4. 轮次循环（会话日志事件与官方 agent-loop 完全同构）

turn/start → user/message → 每发言者: step/start → assistant/chunk →
assistant/message → step/end → turn/end

- 群聊 turn 编号使用偏移空间（GROUP_TURN_BASE = 1_000_000 起），与
agent-loop 的计数器永不冲突；恢复会话时扫描日志续号。
- 流式：每个 chunk 先落 assistant/chunk，用官方 BlockAssembler 组装后写
assistant/message（含 source: {provider, model} provenance 与 usage），
WebUI 按 step/start+assistant/message 契约正常渲染。
- 每会话串行队列；parallelSpeak 时同轮发言者并行生成。
- 失败语义：单发言者失败被记录（GroupTurnStepResult.failure）不影响他人；
全部失败 → turn/end(error)；取消 → aborted。

5. 主动发言（主动模式定时器）

- 每个 active 模式的 agent 按 [minIntervalMs, maxIntervalMs] 随机间隔
挂起一次性定时器（ctx.timer 服务，fiber 自动清理）。
- 触发条件：群聊启用、activeSpeakEnabled 开、未 muteAll、该 agent 未禁言
且 active.enabled、会话无进行中的轮次、距离上次活动 ≥ idleTriggerMs。
- 不满足（临时）→ 30s 后重试；agent 被移除/改模式 → 停止调度。
- 配置变更（group-chat/config-updated）会重置全部主动定时器，使策略即时生效。

已暴露的 Service API

ctx.groupChat
// 读取
.getConfig(): GroupConfig
.getAgent(id): AgentConfig | undefined
.listAgents(): AgentConfig[]
.getStatus(): GroupChatStatus
.watch(cb): () => void
// AI 角色管理
.addAgent(input: AgentInput): Promise
.updateAgent(id, patch): Promise
.removeAgent(id): Promise
.setMuted(id, muted)          // 禁言/解禁
.setMode(id, mode)            // 被动回复 / 主动发言
.setEnabled(id, enabled)
// 群主控制面板
.setMuteAll(muted)            // 禁言全体
.setActiveSpeakEnabled(on)    // 主动发言总开关text
.updateHostRules(patch)
.updateSharedContext(patch)
.setGroupEnabled(on)          // 群聊开关
.setGroupName(name)
// 阶段 2：轮次引擎
.submitMessage(sessionId, text): Promise
.enableSession(sessionId) / .disableSession(sessionId)   // 群聊开关（持久化）
.isSessionEnabled(sessionId) / .listEnabledSessions()
.cancelSession(sessionId)     // 中止进行中的群聊轮次
.getEngine()                  // GroupChatEngine
.listModelCatalog()           // 模型目录（ctx.llm.listProviders + listModels）

WebUI API 路由（/api/group-chat/）：state、config、models（模型目录，供
ModelPicker 同步 DSH 已接入的提供方与模型）、messages（独立群聊页的消息气泡
视图）、attachment（图片字节，按完整 ref 校验后返回）、toggle、submit
（文本 + base64 图片）、cancel、agents（增删改/禁言/模式）、host
（群主规则/共享上下文/全局开关/名称/用户名称显示）。

Cordis 事件（供 Phase 3 / 其他插件订阅）：
group-chat/config-updated、agent-added/updated/removed、
turn-start、agent-speaking、agent-spoken、turn-end、
orchestrator-attached/detached。

数据流

插件以 class plugin 形式加载（与 @deepseek-ai/dsh-agent-default-model 同一模式）：

- static Config = GroupConfigSchema —— 组合入口配置（cordis.patch.yml 的
config: 或空值）由插件注册表校验。
- installSettingsSection(ctx, NS, GroupConfigSchema, entry, hooks) —— 在
group-chat 用户设置命名空间上注册同一 schema，以入口配置为 base；
解析值 = schema 默认值 → 入口 base → ~/.dsh/settings.yaml 用户层。
- 写入路径：ctx.settings.update(NS, patch)（无 settings 服务时抛
GroupChatError 码 NO_SETTINGS，读取仍可用入口配置降级）。
- 每次提交经 group-chat/config-updated 事件广播 (next, prev)，
编排器据此重置主动发言定时器。

核心接口摘要（src/types.ts）

- GroupConfig —— enabled（群聊开关）、name、enabledSessions（开启群聊的会话）、
agents、hostRules、sharedContext。
- AgentConfig —— id、name、provider/model（DSH 模型路由）、
systemPrompt（角色卡）、userPrompt（初始上下文）、mode（passive/active）、
muted（禁言）、enabled、active（主动发言策略）、mentionAliases、triggerKeywords。
- HostRules —— muteAll、activeSpeakEnabled、maxRoundsPerTurn、
maxAgentsPerTurn、parallelSpeak、turnTimeoutMs、mention（@ 语法）。
- SharedContextConfig —— maxMessages（统一 Session Log 滚动窗口）、
transcriptTemplate（[{name}]: {content}）、includeRoleCards。
- GroupTurnResult / GroupTurnStepResult —— 轮次与单发言者结果
（status、cause、failure、messageId）。

开发
bash
npm install --legacy-peer-deps  # devDependencies（peer 全部由 DSH profile 运行池提供，
因此跳过 peer 自动安装；版本与池内 0.1.0-rc.6 对齐）
npm run typecheck    # tsc 主机 + tsc 客户端（tsconfig.client.json）
npm run build        # tsc → lib/（ESM + .d.ts）；tsdown → lib/client.js（WebUI bundle）
npm run smoke        # 裸 Cordis Context 全链路冒烟测试（注册/配置写入/群聊轮次/
提及·触发·禁言选择/共享上下文/主动发言/WebUI API 路由/
消息气泡视图/图片发送/用户名称显示）

安装到 web profile

端用户（从 GitHub 一键安装，推荐）
bash
dsh plugin --profile web add https://github.com/Qx002/dsh-group-chat.git#v0.1.0

该命令在 profile 目录里执行 pnpm add：克隆仓库 → 直接使用仓库内预构建的
lib/*（宿主产物与浏览器 bundle 均已提交，无需在安装时构建）→ 自动把声明了
dsh.bundle 的包并入 dsh.profile.bundles。装完重启 dsh web 即生效，
group-chat 命名空间出现在设置面板。
开发者（本地 link 方式，改代码即时生效）

1. 克隆本仓库到本地，在 ~/.dsh/profiles/web/package.json 的 dependencies
中加入 "dsh-group-chat": "link:"。
2. 在 dsh.profile.bundles 中加入 "dsh-group-chat"（其 dsh.bundle.patch
指向 cordis.patch.yml，自动插入 group-chat 行）。
3. 重启 dsh web。

许可

MIT