export declare interface ActionDescriptor { actionId: string; actionCode: string; actionName: string; description: string; params: Record; needConfirm: boolean; riskLevel: 'safe' | 'caution' | 'danger'; } /** * @deprecated Use `AssistantVisibility` + `AssistantPresentation`. Legacy modes * are mapped for one compatibility cycle: launcher=closed, floating/focus-modal * =compact, drawer=docked, fullscreen=workspace. */ export declare type AiOpenMode = 'launcher' | 'floating' | 'drawer' | 'fullscreen' | 'focus-modal'; export declare type AiThemeMode = 'system' | 'light' | 'dark' | 'custom'; /** A backend-produced insight (never re-derived from rows on the client). */ declare interface AnalysisInsight { type: InsightType; title: string; detail: string; /** Optional references to column keys / row indices backing the insight. */ refs?: string[]; } /** User-visible connectivity, independent from the current turn lifecycle. */ export declare type AssistantConnection = 'idle' | 'connecting' | 'online' | 'reconnecting' | 'offline'; export declare interface AssistantMessage { id: string; conversationId: string; role: MessageRole; type: MessageType; content: string; status: MessageStatus; createdAt: string; finishedAt?: string; metadata?: { chart?: ChartConfig; table?: TableResult; tools?: ToolCall[]; sources?: SourceRef[]; suggestions?: string[]; actions?: ActionDescriptor[]; metrics?: { label: string; value: string | number; unit?: string; trend?: { value: number; direction: 'up' | 'down' | 'flat'; label?: string; }; color?: 'primary' | 'success' | 'warning' | 'danger'; icon?: string; }; errorCode?: string; [key: string]: unknown; }; } /** The three supported layouts for the single assistant shell. */ export declare type AssistantPresentation = 'compact' | 'docked' | 'workspace'; /** Canonical lifecycle for one user turn. */ export declare type AssistantTurnPhase = 'idle' | 'planning' | 'running' | 'awaiting_input' | 'complete' | 'partial' | 'failed' | 'cancelled'; /** * Core protocol types for AI Assistant */ /** Whether the assistant shell is present. The launcher represents `closed`. */ export declare type AssistantVisibility = 'closed' | 'open'; /** * Card payload — discriminated union on `kind`. Mirrors Java `sealed interface * CardData permits TableCard, ChartCard, MetricCard, SourceCard, * SuggestionCard, GlossaryCard, AnalysisCard, CitationCard`. */ declare type CardData = { kind: 'table'; columns: ColumnDef[]; rows: Row[]; total: number; truncated?: boolean; evidenceId?: string; datasetId?: string; artifactId?: string; } | { kind: 'chart'; spec: ChartSpec; /** Original evidence row count; the chart may omit unplottable rows. */ rowCount?: number; /** Source truncation or rows omitted from this chart projection. */ truncated?: boolean; evidenceId?: string; datasetId?: string; artifactId?: string; } | { kind: 'metric'; items: MetricItem[]; } | { kind: 'source'; items: SourceItem[]; } | { kind: 'suggestion'; items: SuggestionItem[]; } | { kind: 'glossary'; columns: ColumnDef[]; } | { kind: 'analysis'; insights: AnalysisInsight[]; } | { kind: 'citation'; items: CitationItem[]; }; /** * v2 protocol — card payloads (discriminated union on `kind`). * * Per REARCHITECTURE-PLAN §4.3 / §4.4: rich content is delivered through a * single `card` event whose `data` is a strongly-typed, `kind`-discriminated * union. Adding a new card = adding a new `kind` here + one frontend registry * entry; the core envelope (events.ts) never changes (CLAUDE.md §12 扩展预留). * * DSH emits only presentation projections; SQL is deliberately absent. * * Pure TS — zero Vue / framework dependency. */ /** Closed enum of card kinds. The `card` event carries one of these. */ declare type CardKind = 'table' | 'chart' | 'metric' | 'source' | 'suggestion' | 'glossary' | 'analysis' | 'citation'; /** Where a card should be rendered within the Process / Answer / Artifact model. */ declare type CardPlacement = 'process' | 'answer' | 'artifact'; export declare interface ChartConfig { type: 'bar' | 'line' | 'pie' | 'heatmap' | 'gantt' | 'scatter' | 'radar'; title: string; data: unknown; options?: Record; } /** Encoding: which column keys map to which visual channels. */ declare interface ChartEncoding { /** Column key for the x axis (category / time). */ x: string; /** One or more column keys for the y axis (measures). For `dual-axis`, * these are the bar measures drawn against the left axis. */ y: string[]; /** Optional column key used to split into series. */ series?: string; /** Radar: one explicit common upper bound for all comparable indicators. */ radarMax?: number; /** dual-axis only: exactly one measure drawn against the right axis. */ lineColumns?: string[]; /** dual-axis only: the label and unit each axis carries. The backend refuses * a dual-axis chart without two distinct labels, so these are always present * when `lineColumns` is. */ axisUnits?: { left: string; right: string; }; } /** * Closed enum of neutral chart kinds. `''` means "no suitable chart — fall back * to table" (mirrors WrenAI's empty chart_type). Frontend maps these to ECharts. */ declare type ChartKind = '' | 'bar' | 'line' | 'pie' | 'scatter' | 'area' | 'grouped-bar' | 'stacked-bar' | 'radar' | 'dual-axis'; /** * Neutral, framework-agnostic chart spec. Backend owns the spec; frontend owns * the ECharts mapping. `data` is the full result set (rows) for plotting. */ declare interface ChartSpec { chartKind: ChartKind; title?: string; /** Stable source shared by chart, table, report, and export artifacts. */ datasetRef?: string; encoding: ChartEncoding; /** Governance-authored display labels keyed by stable semantic column ID. */ columnLabels?: Record; data: Row[]; } /** Metadata of one uploaded conversation attachment (no payload bytes). */ export declare interface ChatAttachmentRef { /** Backend attachment id returned by the upload endpoint. */ id: string; name: string; /** MIME type (best-effort from the browser). */ type: string; size: number; } /** Optional routing hints for one assistant turn. */ export declare interface ChatSendOptions { /** Correlates the shell's optimistic turn with the persisted user message. */ clientRequestId?: string; /** Per-turn reasoning effort hint forwarded to the DSH runtime. */ reasoningEffort?: ReasoningEffort; /** Attachments uploaded for this turn; the backend resolves their text. */ attachments?: ChatAttachmentRef[]; } /** Public request shape for the typed chat-stream endpoint. */ export declare interface ChatStreamRequest extends ChatSendOptions { systemCode: string; conversationId: string; message: string; modelCode?: string; pageContext?: PageContext; } /** A knowledge-base citation entry (Phase 2 预留). */ declare interface CitationItem { docName: string; page: number; section: string; content: string; } declare interface ClarifyOption { value: string; label: string; description?: string; } declare interface ClarifyQuestion { id: string; header: string; question: string; type: 'single_select' | 'multi_select' | 'text' | 'confirm'; required: boolean; options: ClarifyOption[]; } /** * A result-table / glossary column. Semantic fields (displayName/role/...) come * from the backend semantic layer — never re-derived on the client. */ declare interface ColumnDef { key: string; title: string; type?: string; /** Business-friendly Chinese name, e.g. "设备温度". */ displayName?: string; /** Semantic role for analysis/charting. */ role?: ColumnRole; /** Human description, e.g. "通信状态(0正常/1异常)". */ description?: string; /** Display unit, e.g. "℃", "件". */ unit?: string; /** Sensitive columns are stripped before the LLM; flagged here for UI only. */ sensitive?: boolean; } /** Semantic role of a result column (drives glossary + analysis). */ declare type ColumnRole = 'dimension' | 'metric' | 'time'; export declare interface Conversation { id: string; title: string; systemCode: string; sceneCode?: string; modelCode?: string; status: string; createdAt: string; updatedAt: string; } export declare interface CreateAiAssistantOptions { systemCode: string; scene?: string; /** Preferred shell layout. Responsive resolution never overwrites this value. */ defaultPresentation?: AssistantPresentation; /** @deprecated Use `defaultPresentation`. */ defaultMode?: AiOpenMode; theme?: { mode?: AiThemeMode; primaryColor?: string; brandColors?: { primary: string; accent: string; }; }; apiBaseUrl: string; apiBaseUrlMock?: string; modelCode?: string; modelOptions?: ModelOption[]; userProvider?: () => UserInfo; contextProvider?: () => PageContext; requestHeaders?: () => Record; transport?: TransportConfig; features?: FeaturesConfig; i18n?: I18nConfig; onError?: (err: Error) => void; onEvent?: (event: unknown) => void; } declare interface DshPresentationProjection { mode: 'answer' | 'partial' | 'empty' | 'clarification'; answerText: string; evidenceIds: string[]; citations: Array<{ evidenceId: string; datasetId: string; artifactId: string; rowIndex: number; column: string; }>; cards: Array<{ kind: 'table' | 'empty'; evidenceId: string; datasetId: string; artifactId: string; columns: string[]; columnLabels?: Record; previewRows: Array>; rowCount: number; truncated: boolean; } | { kind: 'chart'; evidenceId: string; datasetId: string; artifactId: string; chartKind: Exclude; title?: string; xColumn: string; yColumns: string[]; seriesColumn?: string; radarMax?: number; /** dual-axis only: the single measure drawn against the right axis. */ lineColumns?: string[]; /** dual-axis only: the label and unit each axis carries. */ axisUnits?: { left: string; right: string; }; columns: string[]; columnLabels?: Record; previewRows: Array>; rowCount: number; truncated: boolean; } | { kind: 'metric'; evidenceId: string; datasetId: string; artifactId: string; label: string; value: string; unit?: string; }>; /** Model-selected top-to-bottom narrative/card order. Optional for legacy replay. */ layout?: Array<{ kind: 'markdown'; text: string; } | { kind: 'card'; cardIndex: number; }>; /** Delivery artifact hints (immutable refs); optional for legacy replay. */ attachments?: PublicArtifactRef[]; /** Exact governed URLs selected from successful current-turn web_search results. */ sources?: DshWebSource[]; limitations: string[]; questions: string[]; } /** DSH-owned, evidence-bound presentation projection. */ declare interface DshWebSource { url: string; title?: string; snippet?: string; publishedAt?: string; } export declare interface FeaturesConfig { enableVoice?: boolean; enableFileUpload?: boolean; enableFullscreen?: boolean; enableDrawer?: boolean; enableKnowledge?: boolean; enableActionConfirm?: boolean; } /** Why a run finished. */ declare type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'cancelled' | 'error'; export declare interface I18nConfig { locale?: string; messages?: Record; } declare interface InputAnswer { questionId: string; values: string[]; } /** A clarification response continued as a regular DSH turn. */ declare interface InputResponseRequest { action: 'accept' | 'decline' | 'cancel'; answers: InputAnswer[]; } /** Type of an analysis insight (drives icon/severity on the client). */ declare type InsightType = 'trend' | 'outlier' | 'comparison' | 'summary' | 'anomaly'; declare interface JsonObject { [key: string]: JsonValue; } /** * RFC 6902 JSON Patch op (subset) used by `card.patch` for in-place updates. * Kept narrow on purpose; the transitional path may instead re-send the full * `card` with the same id. */ declare interface JsonPatchOp { op: 'add' | 'remove' | 'replace'; path: string; value?: string | number | boolean | null | Record | unknown[]; } declare type JsonValue = string | number | boolean | null | JsonObject | JsonValue[]; export declare type MessageRole = 'user' | 'assistant' | 'system' | 'tool'; export declare type MessageStatus = 'pending' | 'streaming' | 'success' | 'failed'; export declare type MessageType = 'text' | 'markdown' | 'chart' | 'table' | 'tool' | 'error' | 'metric' | 'action' | 'source' | 'v2_event'; /** A single KPI / metric tile. Multiple tiles share one metric card. */ declare interface MetricItem { label: string; value: string | number; unit?: string; trend?: MetricTrend; /** Display format hint, e.g. "percent", "currency", "integer". */ format?: string; } /** A trend annotation on a metric value. */ declare interface MetricTrend { value: number; direction: TrendDirection; label?: string; } export declare interface ModelOption { code: string; name: string; supportStream: boolean; supportToolCall: boolean; bestFor?: Array<'analysis' | 'knowledge' | 'general'>; maxTokens?: number; } export declare interface PageContext { systemCode: string; pageCode: string; pageName?: string; routePath: string; selectedDeviceIds?: string[]; selectedWorkOrderIds?: string[]; selectedScheduleDate?: string; filters?: Record; extras?: Record; } /** One task in the request-local plan trace exposed only through the trace lane. */ declare interface PlanTraceTask { id: string; name: string; dependsOn: string[]; state: string; priority?: 'high' | 'medium' | 'low'; outcome?: string; toolCallId?: string; toolName?: string; } /** Closed vNext progress lifecycle vocabulary. */ declare type ProgressStatus = 'STARTED' | 'PROGRESSING' | 'RETRYING' | 'AWAITING_INPUT' | 'COMPLETED' | 'FAILED' | 'CANCELLED'; /** * Artifact workbench contracts (public, browser-safe). * * Field shapes mirror `docs/2026-08-28-sidebar-artifact-workbench/02-contract-storage-api.md` * §2/§7. Pure TypeScript, zero dependencies, shared by reducer/store/viewers. */ /** Delivery kinds surfaced by the artifact workbench. */ declare type PublicArtifactKind = 'presentation' | 'document' | 'spreadsheet' | 'image' | 'text' | 'code' | 'data' | 'archive' | 'unknown'; /** Minimal public projection of one immutable artifact version (02 §2). */ declare interface PublicArtifactRef { schemaVersion: '1'; artifactId: string; artifactFamilyId?: string; revision?: number; kind: PublicArtifactKind; format: string; status: PublicArtifactStatus; displayName: string; mimeType?: string; size?: number; checksum?: string; originMessageId?: string; deliveryGroupId?: string; supersedesArtifactId?: string; preview: { strategy: 'pages' | 'image' | 'markdown' | 'text' | 'table' | 'none'; pageCount?: number; state?: 'pending' | 'ready' | 'failed' | 'unavailable'; failure?: { code: string; safeMessage: string; }; }; capabilities: Array<'preview' | 'download' | 'revise'>; createdAt: string; expiresAt: string; } /** Artifact lifecycle statuses (02 §2). */ declare type PublicArtifactStatus = 'queued' | 'generating' | 'validating' | 'previewing' | 'ready' | 'failed' | 'cancelled' | 'expired'; /** DeepSeek reasoning-effort levels accepted by the gateway contract. */ export declare type ReasoningEffort = 'low' | 'medium' | 'high'; /** Risk level for a proposed write action (Action Center 二次确认). */ declare type RiskLevel = 'safe' | 'caution' | 'danger'; /** A single result row: column key → cell value. */ declare type Row = Record; /** * A data-source provenance entry. Discriminated on `kind` to remove the v1 * polymorphism where `table` was sometimes a real table, sometimes a tool name. */ declare type SourceItem = { kind: 'table'; name: string; query?: string; rowCount: number | null; durationMs: number; timestamp: string; } | { kind: 'tool'; name: string; query?: string; rowCount: number | null; durationMs: number; timestamp: string; } | { kind: 'web'; url: string; title?: string; snippet?: string; publishedAt?: string; }; export declare interface SourceRef { table: string; query: string; rowCount: number; durationMs: number; timestamp: string; } /** * The full v2 stream-event union. Discriminated on `type`; every member carries * a monotonic `seq`. */ declare type StreamEvent = { type: 'run.start'; seq: number; conversationId: string; messageId: string; } | { type: 'run.finish'; seq: number; reason: FinishReason; usage: Usage; latencyMs: number; } | { type: 'run.error'; seq: number; code: string; message: string; retriable: boolean; } | { type: 'text.start'; seq: number; partId: string; } | { type: 'text.delta'; seq: number; partId: string; delta: string; } | { type: 'text.end'; seq: number; partId: string; } /** Evidence-checked but provisional narrative, replaced by final presentation. */ | { type: 'answer.preview'; seq: number; previewId: string; text: string; } | { type: 'narration.start'; seq: number; partId: string; } | { type: 'narration.delta'; seq: number; partId: string; delta: string; } | { type: 'narration.end'; seq: number; partId: string; } | { type: 'reasoning.start'; seq: number; partId: string; } | { type: 'reasoning.delta'; seq: number; partId: string; delta: string; } | { type: 'reasoning.end'; seq: number; partId: string; } | { type: 'tool.start'; seq: number; toolCallId: string; toolName: string; group?: string; } | { type: 'tool.input.delta'; seq: number; toolCallId: string; delta: string; } | { type: 'tool.input'; seq: number; toolCallId: string; input: JsonObject; } | { type: 'tool.executing'; seq: number; toolCallId: string; } | { type: 'tool.output'; seq: number; toolCallId: string; output: ToolOutput; status: ToolStatus; } | { type: 'tool.error'; seq: number; toolCallId: string; error: string; diagnostic?: ToolFailureDiagnostic; } | { type: 'presentation'; seq: number; payload: DshPresentationProjection; } | { type: 'stage'; seq: number; stageId: string; label: string; /** Open-enum phase hint, e.g. 'schema-linking' | 'dsl-gen' | 'execute'. */ phase?: string; progress?: number; group?: string; progressId?: string; stepId?: string; status?: ProgressStatus; attempt?: number; elapsedMs?: number; safeSummary?: string; occurredAt?: string; } | { type: 'plan.trace'; seq: number; runId: string; messageId: string; planId: string; planName: string; state: string; version: number; tasks: PlanTraceTask[]; } | { type: 'card'; seq: number; id: string; kind: CardKind; data: CardData; status?: string; group?: string; transient?: boolean; placement?: CardPlacement; anchorId?: string; } | { type: 'card.patch'; seq: number; id: string; patch: JsonPatchOp[]; } | { type: 'action.proposed'; seq: number; actionId: string; title: string; summary?: string; riskLevel: RiskLevel; params: Record; } | { type: 'clarify'; seq: number; requestId: string; questions: ClarifyQuestion[]; }; /** Convenience: the closed set of v2 event `type` discriminants. */ declare type StreamEventType = StreamEvent['type']; /** A structured follow-up suggestion (programmatically routable). */ declare interface SuggestionItem { text: string; /** Optional intent code for programmatic routing. */ intent?: string; /** Optional pre-filled params for the routed intent. */ params?: Record; } /** * A result-table column. The semantic fields (displayName/description/role) are * optional and backward-compatible: when the backend populates them from the * registered column metadata (ColumnConfigDTO) they drive the 字段说明 glossary * and the table-header tooltip; when absent the table renders exactly as before. */ export declare interface TableColumn { key: string; title: string; type?: string; /** Business-friendly Chinese name (e.g. "虚拟温度") for the glossary. */ displayName?: string; /** Human description of the column (e.g. "设备ID", "通信状态(0正常/1异常)"). */ description?: string; /** Semantic role for analysis: dimension / metric / time. */ role?: 'dimension' | 'metric' | 'time'; } export declare interface TableResult { columns: TableColumn[]; rows: Record[]; total?: number; } export declare interface ToolCall { name: string; args: Record; result?: unknown; status: 'pending' | 'running' | 'success' | 'error'; durationMs?: number; } export declare interface ToolDefinition { name: string; description: string; parameters: Record; } export declare type ToolExecutor = (args: Record) => Promise; /** Bounded server-classified failure facts; never raw provider/tool output. */ declare interface ToolFailureDiagnostic { failureType?: 'configuration' | 'transient_model' | 'planning' | 'execution'; retryable?: boolean; automaticRecoveryAttempted?: boolean; retryExhausted?: boolean; replanAllowed?: boolean; diagnosticCode?: string; budgetExceeded?: boolean; inputRequired?: boolean; terminal?: boolean; } /** * Structured tool result (replaces v1's perpetually-null `result`). Always a * populated object describing what the tool did. */ declare interface ToolOutput { executed: boolean; rowCount?: number; durationMs?: number; /** Optional human-readable summary of the tool outcome. */ summary?: string; /** Optional structured payload (kept open for tool-specific extras). */ data?: Record; } /** Tool-call lifecycle status carried by `tool.output`. */ declare type ToolStatus = 'output-available' | 'output-error'; export declare interface ToolStep { stepId: string; toolName: string; title: string; status: 'pending' | 'running' | 'success' | 'error'; args?: Record; /** User-facing explanation of why this step is being run. Not hidden chain-of-thought. */ reason?: string; /** Character offset in the assistant text where this tool step entered the turn. */ contentOffset?: number; result?: unknown; durationMs?: number; message?: string; percent?: number; } export declare interface TransportConfig { type: 'sse' | 'ws'; heartbeatMs?: number; timeoutMs?: number; reconnect?: { max: number; baseMs: number; maxMs?: number; resetOnSuccessMs?: number; }; fetchFallback?: boolean; } /** Direction of a metric trend. */ declare type TrendDirection = 'up' | 'down' | 'flat'; /** Token usage, filled authoritatively on `run.finish` (fixes v1 durationMs=0). */ declare interface Usage { prompt: number; completion: number; total: number; } export declare interface UserInfo { userId: string; username: string; roles: string[]; orgId?: string; areaPermissions?: string[]; dataScope?: 'all' | 'org' | 'area' | 'self'; } declare namespace v2 { export { StreamEvent, StreamEventType, Usage, FinishReason, ToolStatus, ProgressStatus, CardPlacement, ToolOutput, ToolFailureDiagnostic, JsonValue, JsonObject, PlanTraceTask, ClarifyOption, ClarifyQuestion, InputAnswer, InputResponseRequest, RiskLevel, JsonPatchOp, DshPresentationProjection, DshWebSource, CardData, CardKind, ColumnRole, ColumnDef, Row, ChartKind, ChartEncoding, ChartSpec, TrendDirection, MetricTrend, MetricItem, SourceItem, SuggestionItem, InsightType, AnalysisInsight, CitationItem } } export { v2 } export { }