@meiyukichan/dsh-sandore 0.1.0-rc.6

package/lib/client/chat/message-chrome.d.ts

@@ -0,0 +1,51 @@
+/**
+ * message-chrome：抄自 DSH `packages/client/ui-conversation/src/client/chat/message-chrome.ts`。
+ * 用户/agent 消息 IconActions 行共用的时间标签辅助（本地日历日、运行时长、时钟）。
+ * 仅把 locale 面从 conversation 命名空间收窄为 sandore 命名空间（key 集抄进
+ * sandore 字典），逻辑逐字保留。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat/message-chrome
+ */
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+/**
+ * Local calendar-day epoch (ms at local midnight) for an instant.
+ * @param ms - Unix epoch ms.
+ * @returns Midnight of that local calendar day.
+ */
+export declare function startOfLocalDay(ms: number): number;
+/**
+ * Delay until the next local midnight after `ms` (at least 1ms).
+ * @param ms - Unix epoch ms.
+ * @returns Milliseconds until the following local midnight.
+ */
+export declare function msUntilNextLocalMidnight(ms: number): number;
+/**
+ * Localized elapsed-time label shared by running and settled turn chrome.
+ * @param ms - Elapsed duration in milliseconds (negatives clamp to zero).
+ * @param t - Translate seat supplying the duration templates.
+ * @returns Display string in whole seconds.
+ */
+export declare function formatRunDuration(ms: number, t: TranslateNS<'sandore'>): string;
+/**
+ * Sub-turn latency figure: one decimal under ten seconds, whole seconds
+ * beyond. Unit-less so the locale template owns the second suffix.
+ * @param ms - Latency in milliseconds (negatives clamp to zero).
+ * @returns Display number in seconds without unit.
+ */
+export declare function formatLatencySeconds(ms: number): string;
+/**
+ * Decode-throughput figure: whole tokens from ten up, one decimal below.
+ * @param tps - Tokens per second.
+ * @returns Display number without unit.
+ */
+export declare function formatTokensPerSecond(tps: number): string;
+/**
+ * Compact local timestamp for message IconActions. Same calendar day →
+ * `HH:mm`; earlier this year → the `clock.md` date template + clock; other
+ * years → the `clock.ymd` template + clock. Pure: the date templates arrive
+ * through the caller's locale seat.
+ * @param time - Unix epoch ms from the source session event.
+ * @param t - translate seat supplying the `clock.md` / `clock.ymd` templates.
+ * @param now - Reference instant for the day/year cut (defaults to wall clock).
+ * @returns Date-aware clock string (24-hour, zero-padded time).
+ */
+export declare function formatMessageClock(time: number, t: TranslateNS<'sandore'>, now?: number): string;

package/lib/client/chat/reference/ReferenceIcon.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ReferenceIcon：抄自 DSH `packages/client/ui-conversation/src/client/reference/ReferenceIcon.tsx`。
+ * 用户气泡内联引用（@会话/@文件/@文件夹）域字形。逐字保留。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat/reference/ReferenceIcon
+ */
+import type { ReactNode } from 'react';
+/** Reference domains with distinct composer and transcript glyphs. */
+export type ReferenceIconKind = 'session' | 'file' | 'folder';
+/** Props shared by inline reference glyphs. */
+export interface ReferenceIconProps {
+    kind: ReferenceIconKind;
+    size?: number;
+    className?: string | undefined;
+}
+/**
+ * Render the icon that identifies one inline reference domain.
+ * @param props - Reference kind, optional size, and optional CSS class.
+ * @returns The corresponding current-color SVG glyph.
+ */
+export declare function ReferenceIcon({ kind, size, className }: ReferenceIconProps): ReactNode;

package/lib/client/chat/turn-assistant.d.ts

@@ -0,0 +1,12 @@
+/**
+ * turn-assistant：抄自 DSH `packages/client/ui-conversation/src/client/chat/turn-assistant.ts`。
+ * 收集一个 Assistant 生命周期中的可见散文（turn-tail 复制按钮取文本用）。逐字保留。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat/turn-assistant
+ */
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client';
+/**
+ * Collect visible prose from one Assistant lifecycle.
+ * @param blocks - Assistant content blocks.
+ * @returns concatenated text blocks.
+ */
+export declare function assistantText(blocks: readonly AssistantBlock[]): string;

package/lib/client/chat/turn-metrics.d.ts

@@ -0,0 +1,42 @@
+/**
+ * turn-metrics：抄自 DSH `packages/client/ui-conversation/src/client/chat/turn-metrics.ts`。
+ * 已结算 turn 尾部（tail）与 StatsLine 共用的延迟/吞吐折叠。逐字保留。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat/turn-metrics
+ */
+import type { AssistantMessageNode, ConversationNode } from '@deepseek-ai/dsh-client-runtime/client';
+/** Latency and decode-throughput readings for one turn's footer. */
+export interface TurnMetrics {
+    /** First-step TTFT in ms; absent when that step carries no recorded timing. */
+    ttftMs?: number;
+    /** Decode throughput over steps carrying both timing and provider usage. */
+    tokensPerSecond?: number;
+}
+/** One assistant step's derivable latency facts; null marks an unrecorded part. */
+export interface StepReading {
+    /** step/start → first token delta, in ms. */
+    ttftMs: number | null;
+    /** First token delta → final message, in ms. */
+    decodeMs: number | null;
+    /** Provider-reported completion tokens. */
+    outputTokens: number | null;
+}
+type AssistantNode = AssistantMessageNode;
+/**
+ * Read one assistant node's TTFT, decode wall time, and output tokens.
+ * @param node - A settled assistant node.
+ * @returns Per-part readings with `null` for unrecorded values.
+ */
+export declare function assistantStepReading(node: AssistantNode): StepReading;
+/**
+ * Fold assistant nodes into per-turn footer metrics.
+ *
+ * TTFT is the turn's lowest-step request-dispatch-to-first-token reading, so
+ * it is only meaningful when the turn's start is inside
+ * the loaded window (the caller gates on `turnTimings`, which shares that
+ * window). Throughput divides summed output tokens by summed decode wall time,
+ * counting only steps that carry both.
+ * @param nodes - Snapshot nodes of the loaded window.
+ * @returns Turn number → available metrics; turns with none are absent.
+ */
+export declare function deriveTurnMetrics(nodes: readonly ConversationNode[]): Map<number, TurnMetrics>;
+export {};

package/lib/client/chat/use-calendar-day.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Local calendar-day epoch that advances at each local midnight.
+ * @returns Midnight ms for the current local day; updates after the boundary.
+ */
+export declare function useCalendarDay(): number;

package/lib/client/chat/use-throttled-visual-update.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Return a stable scheduler that coalesces visual updates over a frame interval.
+ * @param update - DOM alignment to run after the throttle interval.
+ * @param intervalFrames - frames to wait before applying the latest alignment.
+ * @returns a stable function that schedules the latest update.
+ */
+export declare function useThrottledVisualUpdate(update: () => void, intervalFrames?: number): () => void;

package/lib/client/chat-flow.d.ts

@@ -0,0 +1,110 @@
+/**
+ * chat-flow：轻量子代理面板的纯逻辑层（无 React / 无 DSH 运行时依赖，vitest node
+ * 环境可跑）。对应 DSH ChatView 的「组装层→渲染行」语义：
+ *
+ * - 从 `snapshot.nodes`（公开 `ConversationNode[]`，已排序）取**最新 10 条节点**；
+ * - assistant 节点的 tool-call 块展开为独立工具行（与 DSH 把 tool-call 组装为独立
+ *   'tool-call' 行的行为一致），tool-result 节点与同 callId 的未结算工具行**配对**
+ *   （替换该行——即 DSH 的「同一行从 running 更新为 settled」），窗口截断导致 call
+ *   头不可见时单列（与 DSH 的 soft-fall 一致）；
+ * - `partial`（流式 assistant 增量）追加为流式 agent 行 + 运行中工具行；
+ * - context/compaction/model-retry/turn-error/turn-max-tokens/unknown 等边缘节点映射为
+ *   展示行（对应 DSH `conversation.chat.node` 各 keyed 渲染器）；
+ * - 已完结 turn（`turnTimings`/`turnEnds` 提供时）在其结算 assistant 行后派生
+ *   **turn-tail 行**（对应 DSH 的 'turn-tail' ChatNode：复制 + 运行时长/TTFT/吞吐 +
+ *   branch；branchUnavailable 近似为「结算行不是面板最后一行」）。
+ *
+ * 组件层（StepChatPanel）把 `StepChatFlowRow` 逐一映射为抄自 DSH 的渲染组件。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/chat-flow
+ */
+import type { AssistantBlock, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode, PartialAssistant, RunningToolCall, ToolCallBlock, TurnErrorNode, UnknownSurfaceNode } from '@deepseek-ai/dsh-client-runtime/client';
+/** 面板展示的最大节点数（轻量面板：仅最新 10 条节点）。 */
+export declare const STEP_CHAT_MAX_NODES = 10;
+/**
+ * `buildStepChatFlow` 的最小快照输入面（只读 nodes/partial/runningCalls；
+ * `ConversationSnapshot` 结构上满足它，单测可直接构造小对象）。
+ */
+export interface StepChatFlowInput {
+    readonly nodes: readonly ConversationNode[];
+    readonly partial: PartialAssistant | null;
+    readonly runningCalls: readonly RunningToolCall[];
+    /** 已完结 turn 的时间边界（`ConversationSnapshot.turnTimings`）；缺省不派生 turn-tail。 */
+    readonly turnTimings?: ReadonlyMap<number, {
+        readonly startTime: number;
+        readonly endTime?: number;
+    }>;
+}
+/** turn-tail 展示数据（对齐 DSH `TurnTailChatData` 的展示面；组件层消费）。 */
+export interface StepChatTailData {
+    /** 已完结 turn 号。 */
+    turn: number;
+    /** 结算 assistant 节点 seq（分支锚点）。 */
+    seq: number;
+    /** 结算时间（Unix epoch ms；时钟用）。 */
+    time: number;
+    /** 结算 assistant 的拼接文本（复制按钮取文本）。 */
+    text: string;
+    /** Turn 壁钟时长 ms；turn/start|end 均在窗口内时可用。 */
+    runMs?: number | undefined;
+    /** Turn 首步 TTFT ms；未记录时省略。 */
+    ttftMs?: number | undefined;
+    /** Turn 解码吞吐；未记录时省略。 */
+    tokensPerSecond?: number | undefined;
+    /** 分支不可用（结算 assistant 非窗口尾部等）。 */
+    branchUnavailable: boolean;
+}
+/** 一条展示行（kind 判别；key 为 React key，跨快照稳定）。 */
+export type StepChatFlowRow = {
+    readonly kind: 'user';
+    readonly key: string;
+    readonly node: Extract<ConversationNode, {
+        kind: 'user' | 'steering';
+    }>;
+} | {
+    readonly kind: 'agent';
+    readonly key: string;
+    readonly blocks: readonly AssistantBlock[];
+    readonly streaming: boolean;
+    readonly interrupted: boolean;
+} | {
+    readonly kind: 'tool';
+    readonly key: string;
+    readonly toolName: string;
+    readonly block: ToolCallBlock;
+} | {
+    readonly kind: 'command';
+    readonly key: string;
+    readonly node: CommandNode;
+} | {
+    readonly kind: 'context';
+    readonly key: string;
+    readonly node: ContextMessageNode;
+} | {
+    readonly kind: 'compaction';
+    readonly key: string;
+    readonly node: CompactionSummaryNode;
+} | {
+    readonly kind: 'retry';
+    readonly key: string;
+    readonly node: ModelRetryNode;
+} | {
+    readonly kind: 'turn-error';
+    readonly key: string;
+    readonly node: TurnErrorNode;
+} | {
+    readonly kind: 'turn-max-tokens';
+    readonly key: string;
+} | {
+    readonly kind: 'unknown';
+    readonly key: string;
+    readonly node: UnknownSurfaceNode;
+} | {
+    readonly kind: 'tail';
+    readonly key: string;
+    readonly data: StepChatTailData;
+};
+/**
+ * 快照 → 展示行（最新 10 条节点；assistant 展开为文本行 + 工具行；partial 追加在尾部；
+ * 已完结 turn 派生 turn-tail 行）。
+ */
+export declare function buildStepChatFlow(snapshot: StepChatFlowInput): readonly StepChatFlowRow[];

package/lib/client/composer-selects.d.ts

@@ -0,0 +1,17 @@
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ModelDirectoryFace, PermissionSelectValue } from './model-faces.ts';
+/** 渲染模型触发器 + 两级菜单（复用 DSH 的模型目录数据面）。 */
+export declare function ModelSelectSandore({ t, directory, locked }: {
+    readonly t: TranslateNS<'sandore'>;
+    readonly directory: ModelDirectoryFace;
+    readonly locked: boolean;
+}): import("react").JSX.Element | null;
+/** 渲染权限触发器 + 菜单 + 完全访问确认（行为照 DSH PermissionSelect）。 */
+export declare function PermissionSelectSandore({ t, value, locked, runCommand, queryValue }: {
+    readonly t: TranslateNS<'sandore'>;
+    readonly value: PermissionSelectValue | undefined;
+    readonly locked: boolean;
+    readonly runCommand: (line: string) => Promise<boolean>;
+    /** 权限投影缺失时的回退查询（`/permission` 无参报告）。 */
+    readonly queryValue: () => Promise<PermissionSelectValue | undefined>;
+}): import("react").JSX.Element | null;

package/lib/client/dag-editor-model.d.ts

@@ -0,0 +1,141 @@
+/**
+ * DagEditor 的编辑态模型纯函数（无 React 依赖，可单测）。
+ *
+ * 定义经 `dsh-sandore/yaml`（浏览器安全子路径）解析/序列化，
+ * 编辑态模型即 `WorkflowDefinition`。此处提供新建骨架与五类型 command 工厂，
+ * 供组件初始化与 Step 字段编辑复用，避免在 JSX 中散落结构常量。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/dag-editor-model
+ */
+import type { CommandConfig, DagBranch, InputFromItem, OutputToItem, PassThroughVar, WorkflowDefinition, WorkflowStage, WorkflowStep } from 'dsh-sandore/schema';
+/**
+ * 合并视图 Step（V2 分离式）：Stage 流控位（`{id, branches?}`）与顶层定义
+ * （`definition.steps[id]` 全字段）按 id 合并，供画布/编辑器读取完整字段。
+ */
+export type MergedStep = WorkflowStep & {
+    branches?: DagBranch[];
+};
+/**
+ * 构造某 Stage 的合并 Step 视图：`definition.steps[id]` 定义字段 + `stage.steps[id].branches`
+ * 流控字段。顶层缺定义（旧数据/未同步）时退回 `{id}` 骨架。
+ * @param definition - 工作流定义（含顶层 steps[]）。
+ * @param stage - 目标 Stage（含流控位 steps[]）。
+ * @returns 合并 Step 列表（顺序 = Stage 流控位顺序）。
+ */
+export declare function mergedStepsOf(definition: WorkflowDefinition, stage: WorkflowStage): MergedStep[];
+/** 五类型命令判别字段（对齐 `CommandConfig` discriminated union）。 */
+export type CommandType = CommandConfig['type'];
+/** 全部五类型命令判别字段（编辑表单下拉项）。 */
+export declare const COMMAND_TYPES: readonly CommandType[];
+/** 生成带前缀的唯一 id（`{prefix}-{uuid}`），供 Stage/Step/ipt/opt 节点复用。 */
+export declare function newId(prefix: string): string;
+/** 构造一个新的空 Stage 节点（唯一 `stg-{uuid}` id + 空 steps）。 */
+export declare function createStage(name: string): WorkflowStage;
+/** 构造一个新的输入绑定项（唯一 `ipt-{uuid}` id）。 */
+export declare function createInputFromItem(): InputFromItem;
+/** 构造一个新的输出绑定项（唯一 `opt-{uuid}` id）。 */
+export declare function createOutputToItem(): OutputToItem;
+/** 构造一个空的透传变量项（`name`/`value`/`description` 待填）。 */
+export declare function createPassThroughVar(): PassThroughVar;
+/** 构造一个空的分支项（`next` 待填）。 */
+export declare function createBranch(): DagBranch;
+/** 去掉首尾空白，空串归 `undefined`（用于可选字段清除）。 */
+export declare function trimToUndefined(value: string): string | undefined;
+/** 解析可选的数字输入：空串/非法值归 `undefined`。 */
+export declare function parseOptionalNumber(value: string): number | undefined;
+/** 可编辑的命令文本字段（按类型收窄到 value 内的字段）。 */
+export type CommandTextField = 'command' | 'promptText' | 'agentParamsTemplate' | 'providerId' | 'modelId';
+/** 更新某类型命令的单个文本字段，返回新命令（可选字段空串 → 清除）。 */
+export declare function updateCommandText(command: CommandConfig, field: CommandTextField, value: string): CommandConfig;
+/**
+ * 将保存后的真实 id 回填进定义模型（新建哨兵 `wfl-new` → `wfl-{uuid}`），
+ * 使 YAML 预览基线反映已保存内容。
+ * @param definition - 当前编辑态定义模型。
+ * @param id - 保存回调返回的持久化 id。
+ * @returns id 已更新的定义模型（其余字段不变）。
+ */
+export declare function withDefinitionId(definition: WorkflowDefinition, id: string): WorkflowDefinition;
+/**
+ * 构造某类型的最小合法命令（值为空串，待用户填写）。
+ * @param type - 命令类型。
+ * @returns 该类型的空命令配置。
+ */
+export declare function createCommand(type: CommandType): CommandConfig;
+/** 新建定义的默认 id（首次保存由 Host `createDefinition` 生成 `wfl-{uuid}` 记录键）。 */
+export declare const NEW_DEFINITION_ID = "wfl-new";
+/**
+ * 构造最小合法定义骨架（单个空 Stage），供「新建定义」进入空白 DagEditor。
+ *
+ * `skills`/`mcps`/`agents`/`settings` 显式给出默认值以对齐 `WorkflowDefinitionSchema`
+ * 的 `.default()` 输出类型；`serializeWorkflowYaml` → `parseWorkflowYaml` 可深层相等往返。
+ * @param id - 定义 id（新建默认 `wfl-new`）。
+ * @returns 最小合法定义。
+ */
+export declare function createBlankDefinition(id?: string): WorkflowDefinition;
+/** Stage 节点高度：随 Step 行数增长（封顶 6 行）。 */
+export declare function stageNodeHeight(stepCount: number): number;
+/** 单个 Step 的流出目标（branches[].next + branches[].loop.next，去空）。 */
+export declare function stepTargetsOf(step: MergedStep): string[];
+/** 流控边类型：串行 / 并行分支 / 条件分支 / 循环回边。 */
+export type FlowEdgeKind = 'serial' | 'parallel' | 'conditional' | 'loop';
+/** 流控边规格（供 DAG 画布渲染与 dagre 布局）。 */
+export interface FlowEdgeSpec {
+    readonly source: string;
+    readonly target: string;
+    readonly kind: FlowEdgeKind;
+    /** 边标签（条件分支 label / 循环标识）。 */
+    readonly label?: string | undefined;
+}
+/**
+ * 分支是否为条件分支：有 `condition`（布尔判定命令）才算。无 `condition` = 并行分支
+ * （始终纳入下一批）；有 `loop` 的分支是循环回边（其 `next` 指向更早节点）。
+ */
+export declare function isConditionalBranch(branch: DagBranch): boolean;
+/**
+ * 判断在 Stage 间新增连线 `source → target` 是否会形成回环（Stage DAG 不允许循环）。
+ * 从 target 出发沿既有出边（branches[].next + branches[].loop.next）做可达性搜索：
+ * 若可回到 source，则新增这条边会构成环。自环（source === target）也视为回环。
+ * @param stages - 当前 Stage 列表（不含待加边）。
+ * @param source - 连线起点。
+ * @param target - 连线终点。
+ * @returns 是否构成回环。
+ */
+export declare function wouldCreateStageCycle(stages: readonly WorkflowStage[], source: string, target: string): boolean;
+/**
+ * Stage 层流控边（branches 是唯一出边单元，**无循环**）：有 `condition` 的条件分支
+ * 琥珀虚线（带 label），无 `condition` 的并行分支默认灰实线。未声明流控的孤立 Stage
+ * 按定义顺序串行兜底（画布不画边，仅引擎推进）。
+ * @param stages - 定义内的 Stage 列表。
+ * @returns 去重后的流控边。
+ */
+export declare function stageFlowEdges(stages: readonly WorkflowStage[]): FlowEdgeSpec[];
+/**
+ * Step 层流控边（微流程：并行/条件 branches + **循环回边分支 loop**）。
+ * 条件分支（有 condition）琥珀虚线带 label；循环分支（有 loop）`loop.next` 红色虚线
+ * 回边；无 condition/loop 的并行分支默认灰实线。
+ * @param steps - 某 Stage 内的合并 Step 列表（含 branches 流控）。
+ * @returns 去重后的流控边。
+ */
+export declare function stepFlowEdges(steps: readonly MergedStep[]): FlowEdgeSpec[];
+/** 参与 dagre 布局的节点尺寸。 */
+export interface DagreNodeSpec {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+}
+/** dagre 有向边。 */
+export interface DagreEdgeSpec {
+    readonly source: string;
+    readonly target: string;
+}
+/**
+ * 用 Dagre 计算分层布局（TB = 自上而下垂直流，官方 dagre 示例默认方向）。
+ * 返回节点 id → 左上角坐标（React Flow 的 position 语义，dagre 输出的是中心点，
+ * 需减半宽/高）。
+ * @param nodes - 参与布局的节点。
+ * @param edges - 有向边（自动去重）。
+ * @returns 节点 id → 左上角坐标。
+ */
+export declare function dagreLayout(nodes: readonly DagreNodeSpec[], edges: readonly DagreEdgeSpec[]): Record<string, {
+    x: number;
+    y: number;
+}>;

package/lib/client/describe-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 错误消息归一化（无 React 依赖，可单测）。
+ *
+ * 渲染任意抛出的值为可读消息：`Error` 取 `.message`，其余回落 `String(value)`。
+ * 仅供诊断展示，调用方永不按消息内容路由控制流。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/describe-error
+ */
+/** 渲染任意抛出的值为可读消息（诊断用，永不按消息路由）。 */
+export declare function describeError(error: unknown): string;

package/lib/client/index.d.ts

@@ -0,0 +1,6 @@
+/** sandore Client UI 入口：挂载 sandore Remote 命名空间、注册 sidebar 工作流入口与 shell.overlay 全局工作流 UI。 */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Client 插件依赖的 cordis 服务键。 */
+export declare const inject: string[];
+/** 挂载 sandore 远程命名空间、注册 locale 字典与工作流入口/overlay。 */
+export declare function apply(ctx: ClientContext): Promise<void>;