@roaming-ai/dsh-group-chat 0.2.0

package/lib/types/client/hooks/useMentionState.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 提及状态 hook：封装角色/文件提及相关的派生状态计算
+ * @module dsh-group-chat/client/hooks
+ */
+import { type SnapshotRole } from '../lib/model.ts';
+import type { AtToken } from '../../shared/file-mention-grammar.ts';
+/**
+ * 计算角色提及候选列表
+ * @param mention - 当前 @ token 状态
+ * @param enabledRoles - 启用的角色列表
+ * @returns 角色候选列表（仅在角色模式且 query 为空时返回）
+ */
+export declare function useMentionCandidates(mention: AtToken | null, enabledRoles: SnapshotRole[]): SnapshotRole[];
+/**
+ * 检测输入文本中被 @ 的角色
+ * @param input - 输入文本
+ * @param enabledRoles - 启用的角色列表
+ * @returns 被提及的角色列表
+ */
+export declare function useMentionedRoles(input: string, enabledRoles: SnapshotRole[]): SnapshotRole[];
+/**
+ * 计算安全的候选索引（确保不越界）
+ * @param candidatesLength - 候选列表长度
+ * @param currentIndex - 当前索引
+ * @returns 安全的索引值
+ */
+export declare function useSafeMentionIndex(candidatesLength: number, currentIndex: number): number;

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

@@ -0,0 +1,52 @@
+/**
+ * dsh-group-chat — 浏览器半（web 客户端模块）。
+ *
+ * 经 window.__ModuleLoader__.load 注册（由 tsdown 预设的 banner/footer 闭包
+ * 工厂外壳生成）；factory 返回 Cordis 客户端插件：
+ *  - 「模型群聊」设置页（settings.section）：启停开关，写 host 的 group-chat
+ *    设置命名空间（settings.yaml 持久化）
+ *  - 启用时挂载：侧边栏「群聊」入口（sidebar.panellist）+ 中央主面板（main）
+ *  - 面板数据走 /api/group-chat/*（fetch + SSE），Host 半持有全部状态
+ *  - DSW 原语（@deepseek-ai/dsh-client-ui-primitives，shell 静态种子模块）
+ *    提供按钮/输入/开关/菜单/图标与 MarkdownText 渲染器
+ *
+ * 设计契约（impeccable direction contract；seed key 76db9e37，surface roll
+ * 第 4/6/1 手中用户锁定 C「三区工作台」，代码先行）：
+ * THESIS 三区工作台；FIRST VIEWPORT 左 232px 导航 + 中央会话流 + 右 304px
+ * 上下文栏（窄容器覆盖式、可收起）。完整契约见 docs/DESIGN.md。
+ *
+ * @module dsh-group-chat/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Client plugin id. */
+export declare const name = "group-chat-client";
+/** Required services. */
+export declare const inject: string[];
+/**
+ * Shell 布局槽位的类型声明镜像（运行时由外壳的 layout/sidebar 包声明）：
+ * 中央主面板为 keyed 槽（按 key 挂载），侧边栏面板列表为 list 槽
+ * （id + order + label）。参照 dsh-web 家族外部包的自声明模式。
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** 中央主面板：按 key 挂载一个面板组件。 */
+        'main': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: Record<string, never>;
+        };
+        /** 侧边栏面板列表行：图标 + 标签入口。 */
+        'sidebar.panellist': {
+            kind: 'list';
+            scope: 'root';
+            owner: {
+                size?: number;
+            };
+        };
+    }
+}
+/**
+ * 客户端插件体：设置页常驻注册 + 启用门控挂载侧边栏入口与主面板。
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

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

@@ -0,0 +1,8 @@
+/**
+ * 浏览器半 transport：/api/group-chat/* 同源 JSON 端点。
+ * @module dsh-group-chat/client/api
+ */
+export declare const api: {
+    state: () => Promise<unknown>;
+    action: (payload: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+};

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

@@ -0,0 +1,80 @@
+/**
+ * 浏览器半共享常量与小工具（纯函数，无 React 依赖）。
+ * @module dsh-group-chat/client/model
+ */
+import type { RoleRecord, Snapshot, ToolCallRecord } from '../../core/types.ts';
+/** 会话列表状态派生与文案（core 纯函数，供 NavPanel 渲染）。 */
+export { sessStatus, SESS_STATUS_LABEL, type SessStatus } from '../../core/status.ts';
+/** 角色标识色调色板（与宿主半一致）。 */
+export declare const PALETTE: string[];
+/** Host HTTP API 前缀。 */
+export declare const API_PREFIX = "/api/group-chat";
+/** MarkdownText 渲染文案。 */
+export declare const MD_LABELS: Readonly<{
+    code: {
+        copyLabel: string;
+        copiedLabel: string;
+    };
+    footnotes: "脚注";
+}>;
+/** 快照的 wire 形态（响应里带 ok 标记）。 */
+export type ClientSnapshot = Snapshot & {
+    ok: boolean;
+};
+/** models action 的响应形态。 */
+export interface ModelsResponse {
+    ok: boolean;
+    providers?: {
+        id: string;
+        name?: string;
+    }[];
+    modelsByProvider?: Record<string, {
+        id: string;
+        name?: string;
+    }[]>;
+    error?: string;
+}
+/** efforts action 的响应形态。 */
+export interface EffortsResponse {
+    ok: boolean;
+    efforts?: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    defaultEffort?: string;
+    error?: string;
+}
+/** 快照内的角色/会话/群组视图行。 */
+export type SnapshotRole = Snapshot['roles'][number];
+export type SnapshotSession = Snapshot['sessions'][number];
+export type SnapshotGroup = Snapshot['groups'][number];
+export type SnapshotMessage = Snapshot['messages'][number];
+export declare function roleById(s: ClientSnapshot, id: string | null): SnapshotRole | null;
+export declare function sessById(s: ClientSnapshot, id: string): SnapshotSession | null;
+export declare function groupById(s: ClientSnapshot, id: string): SnapshotGroup | null;
+export declare function escapeRegExp(v: string): string;
+export declare function firstLine(text: string): string;
+export declare function latestLine(text: string): string;
+export declare function fmtTime(ts: number): string;
+/** 角色编辑抽屉的草稿形态（编辑与新建共用）。 */
+export interface RoleDraft {
+    id?: string;
+    name: string;
+    color: string | null;
+    persona: string;
+    provider: string;
+    model: string;
+    temperature?: number;
+    reasoningEffort: string;
+    enabled?: boolean;
+    thinking: boolean;
+}
+export declare function draftFromRole(role: SnapshotRole): RoleDraft;
+export declare function blankDraft(): RoleDraft;
+/** 工具调用行的展示参数。 */
+export type ToolCallView = ToolCallRecord;
+/** 草稿是否可作为角色落库（宿主侧再校验一次）。 */
+export declare function draftMissing(draft: RoleDraft): string;
+/** RoleRecord 兼容视图（快照角色行即其展示子集）。 */
+export type RoleView = RoleRecord;

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

@@ -0,0 +1,10 @@
+/**
+ * 浏览器半样式：CSS 以内联字符串承载（刻意不迁移 CSS Modules 管线——
+ * 类名需保持原样，侧栏入口的 “newSession” 类名是任务看板等 DOM 注入式
+ * 面板识别“侧边栏导航点击”的跨插件标记，哈希化会破坏该约定）。
+ * 工厂执行时幂等注入 <style>，loader 卸载时按 data-plugin 摘除标签。
+ * @module dsh-group-chat/client/styles
+ */
+export declare const CSS: string;
+/** 工厂执行时幂等注入样式标签（loader 卸载时按 data-plugin 摘除）。 */
+export declare function injectStyles(): void;

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

@@ -0,0 +1,17 @@
+/**
+ * 浏览器半 UI 基座：DSW 原语（shell 静态种子模块，loader 模块表 external）
+ * 与动态图标 / 命令式 createElement 辅助。组件主体已 JSX 化（.tsx）；此处
+ * 仅保留 slot 注册回调与动态图标表需要的少量命令式辅助。
+ * @module dsh-group-chat/client/ui
+ */
+import { type ReactNode } from 'react';
+import * as P from '@deepseek-ai/dsh-client-ui-primitives';
+export { P };
+/** 命令式 createElement（仅 slot 注册回调用）。 */
+export declare const h: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => ReactNode;
+/** 图标组件的调用形态。 */
+export type IconComponent = (props: Record<string, unknown>) => ReactNode;
+/** 按名取 DSW 原语（图标表驱动）。 */
+export declare function pickPrimitive(name: string): IconComponent;
+/** 以统一 size 包装图标组件调用（放在 JSX 子元素位）。 */
+export declare function Icon(comp: unknown, size: number, extra?: Record<string, unknown>): ReactNode;

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

@@ -0,0 +1,78 @@
+/**
+ * 浏览器半共享常量与小工具（纯函数，无 React 依赖）。
+ * @module dsh-group-chat/client/model
+ */
+import type { RoleRecord, Snapshot, ToolCallRecord } from '../core/types.ts';
+/** 角色标识色调色板（与宿主半一致）。 */
+export declare const PALETTE: string[];
+/** Host HTTP API 前缀。 */
+export declare const API_PREFIX = "/api/group-chat";
+/** MarkdownText 渲染文案。 */
+export declare const MD_LABELS: Readonly<{
+    code: {
+        copyLabel: string;
+        copiedLabel: string;
+    };
+    footnotes: "脚注";
+}>;
+/** 快照的 wire 形态（响应里带 ok 标记）。 */
+export type ClientSnapshot = Snapshot & {
+    ok: boolean;
+};
+/** models action 的响应形态。 */
+export interface ModelsResponse {
+    ok: boolean;
+    providers?: {
+        id: string;
+        name?: string;
+    }[];
+    modelsByProvider?: Record<string, {
+        id: string;
+        name?: string;
+    }[]>;
+    error?: string;
+}
+/** efforts action 的响应形态。 */
+export interface EffortsResponse {
+    ok: boolean;
+    efforts?: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    defaultEffort?: string;
+    error?: string;
+}
+/** 快照内的角色/会话/群组视图行。 */
+export type SnapshotRole = Snapshot['roles'][number];
+export type SnapshotSession = Snapshot['sessions'][number];
+export type SnapshotGroup = Snapshot['groups'][number];
+export type SnapshotMessage = Snapshot['messages'][number];
+export declare function roleById(s: ClientSnapshot, id: string | null): SnapshotRole | null;
+export declare function sessById(s: ClientSnapshot, id: string): SnapshotSession | null;
+export declare function groupById(s: ClientSnapshot, id: string): SnapshotGroup | null;
+export declare function escapeRegExp(v: string): string;
+export declare function firstLine(text: string): string;
+export declare function latestLine(text: string): string;
+export declare function fmtTime(ts: number): string;
+/** 角色编辑抽屉的草稿形态（编辑与新建共用）。 */
+export interface RoleDraft {
+    id?: string;
+    name: string;
+    color: string | null;
+    persona: string;
+    provider: string;
+    model: string;
+    temperature?: number;
+    reasoningEffort: string;
+    enabled?: boolean;
+    thinking: boolean;
+}
+export declare function draftFromRole(role: SnapshotRole): RoleDraft;
+export declare function blankDraft(): RoleDraft;
+/** 工具调用行的展示参数。 */
+export type ToolCallView = ToolCallRecord;
+/** 草稿是否可作为角色落库（宿主侧再校验一次）。 */
+export declare function draftMissing(draft: RoleDraft): string;
+/** RoleRecord 兼容视图（快照角色行即其展示子集）。 */
+export type RoleView = RoleRecord;

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

@@ -0,0 +1,10 @@
+/**
+ * 主面板：三区工作台——左导航栏（搜索 + 群组→会话目录树）、中央会话流
+ * （@成员 点名 + markdown 渲染 + 思考折叠）、右上下文栏（群成员角色卡 +
+ * 工作区目录），右栏可收起，角色编辑走右侧滑出抽屉。
+ *
+ * 面板数据走 /api/group-chat/*（fetch + SSE），Host 半持有全部状态。
+ * @module dsh-group-chat/client/panel
+ */
+import { type ReactNode } from 'react';
+export declare function GroupChatPanel(): ReactNode;

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

@@ -0,0 +1,15 @@
+/**
+ * 设置页：启停开关（settings.section 插槽）。写 host 的 group-chat 设置
+ * 命名空间（settings.yaml 持久化）。
+ * @module dsh-group-chat/client/settings
+ */
+import { type ReactNode } from 'react';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** Host 侧注册的设置命名空间 shape。 */
+interface GroupChatSettings {
+    enabled?: boolean;
+}
+export declare function GroupChatSettingsSection(props: {
+    settingsScope: SettingsScope<GroupChatSettings>;
+}): ReactNode;
+export {};

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

@@ -0,0 +1,10 @@
+/**
+ * 浏览器半样式：CSS 以内联字符串承载（刻意不迁移 CSS Modules 管线——
+ * 类名需保持原样，侧栏入口的 “newSession” 类名是任务看板等 DOM 注入式
+ * 面板识别“侧边栏导航点击”的跨插件标记，哈希化会破坏该约定）。
+ * 工厂执行时幂等注入 <style>，loader 卸载时按 data-plugin 摘除标签。
+ * @module dsh-group-chat/client/styles
+ */
+export declare const CSS: string;
+/** 工厂执行时幂等注入样式标签（loader 卸载时按 data-plugin 摘除）。 */
+export declare function injectStyles(): void;

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

@@ -0,0 +1,17 @@
+/**
+ * 浏览器半 UI 基座：DSW 原语（shell 静态种子模块，loader 模块表 external）
+ * 与动态图标 / 命令式 createElement 辅助。组件主体已 JSX 化（.tsx）；此处
+ * 仅保留 slot 注册回调与动态图标表需要的少量命令式辅助。
+ * @module dsh-group-chat/client/ui
+ */
+import { type ReactNode } from 'react';
+import * as P from '@deepseek-ai/dsh-client-ui-primitives';
+export { P };
+/** 命令式 createElement（仅 slot 注册回调用）。 */
+export declare const h: (type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]) => ReactNode;
+/** 图标组件的调用形态。 */
+export type IconComponent = (props: Record<string, unknown>) => ReactNode;
+/** 按名取 DSW 原语（图标表驱动）。 */
+export declare function pickPrimitive(name: string): IconComponent;
+/** 以统一 size 包装图标组件调用（放在 JSX 子元素位）。 */
+export declare function Icon(comp: unknown, size: number, extra?: Record<string, unknown>): ReactNode;

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

@@ -0,0 +1,29 @@
+/**
+ * 通用工具函数
+ * @module dsh-group-chat/client/utils
+ */
+import { type AtToken } from '../../shared/file-mention-grammar.ts';
+/** HTML 转义（芯片以 execCommand('insertHTML') 注入，角色名需转义）。 */
+export declare function escapeHtml(v: string): string;
+export declare function execCommand(commandId: 'delete' | 'insertHTML' | 'insertText' | 'insertLineBreak', value?: string): boolean;
+/**
+ * contenteditable 输入区 → 纯文本序列化（发送/参与判定的唯一事实源）：
+ * 文本节点原样；<br> → 换行；角色芯片（.dsgc-chipin[data-role-id]）展开回「@名字␠」；
+ * 文件芯片（.dsgc-chipin[data-kind=file]）展开回「@path」或「@"path with spaces"」；
+ * DIV/P 块前补换行（防粘贴残留的块级包裹）。
+ */
+export declare function serializeInput(root: HTMLElement): string;
+/** @角色芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+export declare function chipHtml(role: {
+    id: string;
+    name: string;
+    color?: string;
+}): string;
+/** @文件芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+export declare function fileChipHtml(path: string, kind: 'file' | 'directory'): string;
+/**
+ * 光标前的活跃 @token（角色或文件弹层触发判定）。
+ *
+ * @returns AtToken 对象，包含 prefix/query/quoted；无返回 null
+ */
+export declare function queryAtCaret(): AtToken | null;

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

@@ -0,0 +1,22 @@
+/**
+ * 通用工具函数
+ * @module dsh-group-chat/client/utils
+ */
+/** HTML 转义（芯片以 execCommand('insertHTML') 注入，角色名需转义）。 */
+export declare function escapeHtml(v: string): string;
+export declare function execCommand(commandId: 'delete' | 'insertHTML' | 'insertText' | 'insertLineBreak', value?: string): boolean;
+/**
+ * contenteditable 输入区 → 纯文本序列化（发送/参与判定的唯一事实源）：
+ * 文本节点原样；<br> → 换行；@提及芯片（.dsgc-chipin）展开回「@名字␠」；
+ * DIV/P 块前补换行（防粘贴残留的块级包裹）。手打纯文本 @名字 与芯片展开
+ * 结果同形——语义统一由 mentionedRoles 正则承载（芯片=糖，正则=真）。
+ */
+export declare function serializeInput(root: HTMLElement): string;
+/** @提及芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+export declare function chipHtml(role: {
+    id: string;
+    name: string;
+    color?: string;
+}): string;
+/** 光标前未闭合的 @词（弹层触发判定）；无返回 null */
+export declare function queryAtCaret(): string | null;

package/lib/types/core/json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 记录 → 落盘 JSON 的纯序列化（core 层；可选字段无则省略）。
+ * @module dsh-group-chat/core/json
+ */
+import type { MessageRecord, RoleRecord } from './types.ts';
+/** 消息 → 落盘 JSON（可选字段无则省略；兼容保留 error）。 */
+export declare function messageJson(m: Partial<MessageRecord> | undefined): Record<string, unknown> | null;
+/** 角色 → 落盘 JSON（groupId 由目录归属，不再写入）。 */
+export declare function roleJson(r: Partial<RoleRecord>): Record<string, unknown>;

package/lib/types/core/status.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 会话状态派生（纯函数）：从快照 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 declare const SESS_STATUS_LABEL: Record<SessStatus, string>;
+/** 派生单个会话的列表状态（run 为快照的 run 视图）。 */
+export declare function sessStatus(run: Snapshot['run'], sessionId: string): SessStatus;

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

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