@roaming-ai/dsh-group-chat 0.2.0

package/lib/types/host/persistence/store.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 持久化（PERSISTENCE.md v2.1：会话级文件隔离）。
+ *
+ * 目录布局（每群组一目录，一会话一文件）：
+ *   <dir>/ledger.json                              群组/会话清单（schema 3，纯清单，pretty；群组含 permissionTier）
+ *   <dir>/<group-id>/workspaceDir                  工作区目录设置（纯文本一行）
+ *   <dir>/<group-id>/roles.json                    群组角色（schema 1，紧凑）
+ *   <dir>/<group-id>/sessions/session-<uuid>.json   会话（schema 1，自包含，紧凑）
+ *
+ * 原子写 tmp+fsync+rename（每目录一次 fsync）；单实例 .lock；损坏隔离重建；
+ * 写失败保留脏标记；v1 自动迁移。
+ * @module dsh-group-chat/host/persistence/store
+ */
+import type { GroupRecord } from '../../core/types.ts';
+/** DSH 主目录；DSH_GROUP_CHAT_STORE 供测试覆盖存储位置。 */
+export declare const DSH_HOME: string;
+/** 存储根目录。 */
+export declare const STORE_DIR: string;
+/** 会话文件名 → 会话 id。 */
+export declare function sessionFileMatch(name: string): string | null;
+export declare class Store {
+    readonly dir: string;
+    readonly ledgerFile: string;
+    private readonly lockFile;
+    private lockFd;
+    constructor(dir: string);
+    groupDir(groupId: string): string;
+    sessionsDir(groupId: string): string;
+    sessionFile(groupId: string, sessionId: string): string;
+    rolesFile(groupId: string): string;
+    workspaceFile(groupId: string): string;
+    private acquireLock;
+    release(): void;
+    fsyncDir(dir: string): void;
+    /** 原子写：tmp+fsync+rename；目录 fsync 由调用方按 flush 批量执行（每目录一次）。 */
+    atomicWrite(file: string, text: string): void;
+    quarantine(file: string): void;
+    /** 读 JSON；缺失返回 null；损坏则隔离后返回 null。 */
+    loadJson(file: string): unknown;
+    readWorkspace(groupId: string): string;
+    /** hydrate 残留清理：.tmp-* 删除；同前缀 .corrupt-* 只保留最近 1 份。 */
+    cleanup(): void;
+    /** v1（ledger+messages 双文件）→ v2 一次性迁移；幂等，messages.json 只归档从不删除。 */
+    migrateV1(): void;
+}
+/** ledger 清单的读取形态（hydrate 用；allowCommands 为 v2 遗留字段，读取时经 migrateTier 迁移）。 */
+export interface LedgerDocument {
+    schema?: number;
+    groups?: {
+        id: string;
+        name?: string;
+        permissionTier?: string;
+        allowCommands?: boolean;
+    }[];
+    sessions?: {
+        id: string;
+        groupId: string;
+    }[];
+}
+/** 从磁盘目录回收群组 id 列表（ledger 缺失/损坏时的兜底路径）。 */
+export declare function scanGroupIds(dir: string): string[];
+/** 扫描群组目录下的会话文件（ledger 缺失/损坏时的兜底路径）。 */
+export declare function scanSessionIds(store: Store, groupId: string): string[];
+/** 空群组记录构造（hydrate 兜底路径用）。 */
+export declare function emptyGroup(id: string, name: string): GroupRecord;

package/lib/types/host/persistence.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 持久化（PERSISTENCE.md v2.1）：事件驱动脏标记合并落盘 + 启动恢复。
+ * 锁失败/写失败时降级为内存态运行（console 告警）。
+ * @module dsh-group-chat/host/persistence
+ */
+import type { HostState } from './state.ts';
+/** 持久化面。 */
+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;
+}
+/**
+ * 创建持久化面：构造即完成 store 初始化 + hydrate（v1 迁移 → 残留清理 →
+ * 清单 → 群组数据 → 会话文件；缺文件空重建；补建默认会话/群组立即落盘）。
+ */
+export declare function createPersistence(core: HostState): Persistence;

package/lib/types/host/routes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * HTTP 路由（经 webServer 暴露）：
+ *   GET  /api/group-chat/state   全量快照
+ *   POST /api/group-chat/action   { kind: mutate|send|stop|models|preview, ... }
+ *   GET  /api/group-chat/events   SSE，状态变化时推送节流后的全量快照
+ * @module dsh-group-chat/host/routes
+ */
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { GroupChatService } from './service.ts';
+/** 构建群聊的三条 HTTP 路由。 */
+export declare function makeGroupChatRoutes(service: GroupChatService): WebRoute[];

package/lib/types/host/service.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 群聊宿主服务（组合根）：装配各层模块并暴露对路由/入口的面。
+ * 目录分层（对齐 src/client 的分层模式：每层一目录 + index.ts barrel）：
+ *   state.ts       共享状态容器（四张表 + run + 可变槽位；kernel，根级）
+ *   broadcast.ts   SSE 广播（节流）+ touch + 全量快照（kernel 读模型，根级）
+ *   persistence/   持久化（store 文件原语 + 脏标记合并落盘 + 启动恢复）
+ *   materials/     资料读取与路径解析 + 目录浏览器
+ *   tools/         工具执行（沙箱 + 确认闸门）
+ *   engine/        对话引擎（conversation：speak/runLoop；retitle：标题整理）
+ *   api/           HTTP 传输（http 护栏 + routes 路由）与动作分发（actions）
+ * @module dsh-group-chat/host/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Snapshot } from '../core/types.ts';
+/** 服务对路由/入口暴露的面。 */
+export interface GroupChatService {
+    snapshot(): Snapshot;
+    handleAction(body: unknown): Promise<unknown>;
+    subscribePush(push: () => void): () => void;
+    /** 设置停用时中止正在进行的群聊。 */
+    stopAll(): void;
+    /** 卸载/热重载：唤醒确认等待 + kill 子进程 → 同步最终 flush → 释放锁。 */
+    dispose(): void;
+}
+/**
+ * 创建群聊宿主服务（装配各模块；持久化锁失败时降级内存态运行）。
+ */
+export declare function createGroupChatService(ctx: Context): GroupChatService;

package/lib/types/host/state.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 群聊宿主服务共享状态容器：四张表 + run（对话进行时状态）+ 可变槽位
+ * （store / revision / idSeq / lastCreated）。各功能模块（persistence /
+ * broadcast / materials / tools / conversation / actions）以工厂装配到同一
+ * 容器上，模块间只经显式依赖传递；容器本身只含数据与稳定引用，不含行为。
+ * @module dsh-group-chat/host/state
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Store } from './persistence/store.ts';
+import type { GroupRecord, LastCreated, MessageRecord, RoleRecord, RunState, SessionRecord } from '../core/types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentDefaultModel?: {
+            currentSelection(): {
+                provider: string;
+                model: string;
+            };
+        };
+    }
+}
+/** 角色标识色板（新增角色依序取色）。 */
+export declare const PALETTE: string[];
+/** 宿主服务共享状态容器（见模块注释；可变原始值一律经 core.* 访问）。 */
+export interface HostState {
+    ctx: Context;
+    llm: Context['llm'];
+    fs: Context['fs'];
+    groups: Map<string, GroupRecord>;
+    sessions: Map<string, SessionRecord>;
+    roles: Map<string, RoleRecord>;
+    messages: Map<string, MessageRecord>;
+    run: RunState;
+    /** 持久化句柄；锁失败降级内存态为 null，dispose 后置 null。 */
+    store: Store | null;
+    /** 快照版本号：touch() 递增。 */
+    revision: number;
+    /** id 序号（hydrate 后推进到历史最大值 + 1）。 */
+    idSeq: number;
+    nid: (p: string) => string;
+    /** 最近一次创建的群组/会话，供客户端定位选中项。 */
+    lastCreated: LastCreated | null;
+    newSession: (groupId: string, name?: string) => SessionRecord;
+}
+/** 创建共享状态容器（仅数据与稳定引用，不含行为）。 */
+export declare function createHostState(ctx: Context): HostState;

package/lib/types/host/store.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 持久化（PERSISTENCE.md v2.1：会话级文件隔离）。
+ *
+ * 目录布局（每群组一目录，一会话一文件）：
+ *   <dir>/ledger.json                              群组/会话清单（schema 3，纯清单，pretty；群组含 permissionTier）
+ *   <dir>/<group-id>/workspaceDir                  工作区目录设置（纯文本一行）
+ *   <dir>/<group-id>/roles.json                    群组角色（schema 1，紧凑）
+ *   <dir>/<group-id>/sessions/session-<uuid>.json   会话（schema 1，自包含，紧凑）
+ *
+ * 原子写 tmp+fsync+rename（每目录一次 fsync）；单实例 .lock；损坏隔离重建；
+ * 写失败保留脏标记；v1 自动迁移。
+ * @module dsh-group-chat/host/store
+ */
+import type { GroupRecord } from '../core/types.ts';
+/** DSH 主目录；DSH_GROUP_CHAT_STORE 供测试覆盖存储位置。 */
+export declare const DSH_HOME: string;
+/** 存储根目录。 */
+export declare const STORE_DIR: string;
+/** 会话文件名 → 会话 id。 */
+export declare function sessionFileMatch(name: string): string | null;
+export declare class Store {
+    readonly dir: string;
+    readonly ledgerFile: string;
+    private readonly lockFile;
+    private lockFd;
+    constructor(dir: string);
+    groupDir(groupId: string): string;
+    sessionsDir(groupId: string): string;
+    sessionFile(groupId: string, sessionId: string): string;
+    rolesFile(groupId: string): string;
+    workspaceFile(groupId: string): string;
+    private acquireLock;
+    release(): void;
+    fsyncDir(dir: string): void;
+    /** 原子写：tmp+fsync+rename；目录 fsync 由调用方按 flush 批量执行（每目录一次）。 */
+    atomicWrite(file: string, text: string): void;
+    quarantine(file: string): void;
+    /** 读 JSON；缺失返回 null；损坏则隔离后返回 null。 */
+    loadJson(file: string): unknown;
+    readWorkspace(groupId: string): string;
+    /** hydrate 残留清理：.tmp-* 删除；同前缀 .corrupt-* 只保留最近 1 份。 */
+    cleanup(): void;
+    /** v1（ledger+messages 双文件）→ v2 一次性迁移；幂等，messages.json 只归档从不删除。 */
+    migrateV1(): void;
+}
+/** ledger 清单的读取形态（hydrate 用；allowCommands 为 v2 遗留字段，读取时经 migrateTier 迁移）。 */
+export interface LedgerDocument {
+    schema?: number;
+    groups?: {
+        id: string;
+        name?: string;
+        permissionTier?: string;
+        allowCommands?: boolean;
+    }[];
+    sessions?: {
+        id: string;
+        groupId: string;
+    }[];
+}
+/** 从磁盘目录回收群组 id 列表（ledger 缺失/损坏时的兜底路径）。 */
+export declare function scanGroupIds(dir: string): string[];
+/** 扫描群组目录下的会话文件（ledger 缺失/损坏时的兜底路径）。 */
+export declare function scanSessionIds(store: Store, groupId: string): string[];
+/** 空群组记录构造（hydrate 兜底路径用）。 */
+export declare function emptyGroup(id: string, name: string): GroupRecord;

package/lib/types/host/tools/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 工具执行层统一导出
+ * @module dsh-group-chat/host/tools
+ */
+export { createTools } from './tools.ts';
+export type { Tools } from './tools.ts';

package/lib/types/host/tools/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 工具执行（TOOLS.md §2：沙箱 / §3：确认闸门）：read_file / list_dir /
+ * run_command 三件套；realpath 硬边界 + 分隔符比较；run_command 按群组
+ * 权限档位走逐条确认或直接执行。
+ * @module dsh-group-chat/host/tools
+ */
+import { TOOL_SCHEMAS } from '../../core/tools.ts';
+import type { GroupRecord, ToolExecution } from '../../core/types.ts';
+import type { HostState } from '../state.ts';
+/** 工具面。 */
+export interface Tools {
+    /** 执行一次工具调用（args 解析 + 分发 + 计时；确认闸门在 run_command 内）。 */
+    executeTool: (g: GroupRecord, root: string, tc: {
+        id: string;
+        name: string;
+        args: string;
+    }) => Promise<ToolExecution>;
+    /** 工具 schema（view_only 档剔除 run_command）。 */
+    buildToolSchemas: (g: GroupRecord) => (typeof TOOL_SCHEMAS)[number][];
+    /** 置 pendingConfirm 后无限等待，confirmCommand/stop/dispose 唤醒。 */
+    requestConfirmation: (toolCallId: string, args: Record<string, unknown>) => Promise<boolean>;
+    /** 唤醒确认等待（以拒绝放行；置空 pendingConfirm）。 */
+    wakeConfirm: () => void;
+    /** kill 正在执行的命令子进程。 */
+    killChild: () => void;
+}
+/** 创建工具面。 */
+export declare function createTools(core: HostState, touch: () => void): Tools;

package/lib/types/host/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 工具执行（TOOLS.md §2：沙箱 / §3：确认闸门）：read_file / list_dir /
+ * run_command 三件套；realpath 硬边界 + 分隔符比较；run_command 按群组
+ * 权限档位走逐条确认或直接执行。
+ * @module dsh-group-chat/host/tools
+ */
+import { TOOL_SCHEMAS } from '../core/tools.ts';
+import type { GroupRecord, ToolExecution } from '../core/types.ts';
+import type { HostState } from './state.ts';
+/** 工具面。 */
+export interface Tools {
+    /** 执行一次工具调用（args 解析 + 分发 + 计时；确认闸门在 run_command 内）。 */
+    executeTool: (g: GroupRecord, root: string, tc: {
+        id: string;
+        name: string;
+        args: string;
+    }) => Promise<ToolExecution>;
+    /** 工具 schema（view_only 档剔除 run_command）。 */
+    buildToolSchemas: (g: GroupRecord) => (typeof TOOL_SCHEMAS)[number][];
+    /** 置 pendingConfirm 后无限等待，confirmCommand/stop/dispose 唤醒。 */
+    requestConfirmation: (toolCallId: string, args: Record<string, unknown>) => Promise<boolean>;
+    /** 唤醒确认等待（以拒绝放行；置空 pendingConfirm）。 */
+    wakeConfirm: () => void;
+    /** kill 正在执行的命令子进程。 */
+    killChild: () => void;
+}
+/** 创建工具面。 */
+export declare function createTools(core: HostState, touch: () => void): Tools;

package/lib/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * dsh-group-chat — DSH 模型群聊（host 平面组合插件，host + client 双半）。
+ *
+ * Host 半职责：
+ *  - 群组 / 会话 / 角色 / 消息的状态机，会话级文件持久化于
+ *    ~/.dsh/storages/group-chat/（PERSISTENCE.md v2.1：每群组一目录，
+ *    sessions/session-<uuid>.json 一会话一文件；roles.json 与 workspaceDir
+ *    随群组目录；ledger.json 纯清单；原子写 tmp+fsync+rename（每目录一次
+ *    fsync）；单实例 .lock；损坏隔离重建；写失败保留脏标记；v1 自动迁移）
+ *    数据模型：Group 1..N Session，消息挂在会话上；角色与工作区目录挂在群组上
+ *  - 群组与会话的增删改；群组/会话检索由客户端在快照上过滤
+ *  - 角色发言经 `llm` 服务流式生成，按角色绑定的 provider/model 路由
+ *  - 群组工作区目录经 `fs` 服务读取（根下一层文本文件，最多 20 个），
+ *    以「共享资料」块注入每个角色的 system 提示词；无独立笔记/文件清单
+ *  - 经 `webServer` 暴露 HTTP API：
+ *      GET  /api/group-chat/state   全量快照
+ *      POST /api/group-chat/action   { kind: mutate|send|stop|confirmCommand|models|efforts|browse|fileSearch, ... }
+ *      GET  /api/group-chat/events   SSE，状态变化时推送节流后的全量快照
+ *
+ * 设置命名空间 `group-chat`（settings.yaml 持久化）：`enabled` 控制浏览器半
+ * 的侧边栏入口与主面板挂载；关闭时会中止正在进行的群聊。
+ *
+ * @module dsh-group-chat
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from 'schemastery';
+export declare const name = "group-chat";
+export declare const inject: string[];
+/** 设置命名空间；浏览器半拼写同一值，两边不共享代码。 */
+export declare const SETTINGS_NAMESPACE: SettingsNamespace;
+export interface Config {
+    enabled?: boolean;
+}
+/** 设置 schema：目前只有启停一个开关。 */
+export declare const Config: z<Config>;
+/**
+ * Host 半插件体：状态机服务 + HTTP 路由 + 设置接入。
+ * mountOnce 保证同名包每进程至多挂载一次（bundle 聚合与独立安装并存场景）。
+ */
+export declare const apply: (ctx: Context, config?: Config) => void;

package/lib/types/mount-once.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export declare function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T;

package/lib/types/shared/file-mention-grammar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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).
+ *
+ * @module dsh-group-chat/shared
+ */
+export interface AtToken {
+    /** Full matched prefix including @ and optional quotes */
+    prefix: string;
+    /** Query fragment after @ (unquoted content) */
+    query: string;
+    /** Whether the token uses quoted form @"..." */
+    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 declare function activeAtToken(line: string, cursor: number): AtToken | 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 declare function formatFileMention(candidate: FileCandidate, preserveQuote: boolean): string | undefined;

package/lib/types/shared/file-mention-grammar.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Tests for vendored @file token grammar.
+ * @vitest-environment node
+ */
+export {};

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@roaming-ai/dsh-group-chat",
+  "description": "DSH 模型群聊：多模型角色群组对话面板。角色绑定不同 provider/model，群内共享对话记录；设置页支持启用/停用。",
+  "version": "0.2.0",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "lib/**/*.d.ts",
+    "lib/**/*.d.ts.map",
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/localSummer/dsh-group-chat"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.5-rc.1"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ]
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-file-reference": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-file-reference-local": "0.1.5-rc.2",
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-fs": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-workspace": "^0.1.5-rc.1",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --pretty false",
+    "pack:check": "pnpm build && pnpm pack --dry-run"
+  }
+}